Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
202 lines (167 loc) · 6.47 KB

ARCHITECTURE.md

File metadata and controls

202 lines (167 loc) · 6.47 KB

SteerDock Architecture

Current Architecture: Monolithic

SteerDock currently uses a monolithic architecture with a single backend service and frontend application.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                    Frontend                         │
│              (React + TypeScript)                   │
│                   Port: 5151                        │
└──────────────────┬──────────────────────────────────┘
                   │ HTTP(s)/WebSocket
                   ▼
┌─────────────────────────────────────────────────────┐
│                Backend (Go)                         │
│                - REST API                           │
│                - WebSocket                          │
│                - Authentication                     │
│                - Docker Management                  │
│                Port: 8383                           │
└──────────────────┬──────────────────────────────────┘
                   │
        ┌──────────┼──────────┐
        │          │          │
        ▼          ▼          ▼
   ┌────────┐ ┌────────┐ ┌────────┐
   │Database│ │ Redis  │ │ Docker │
   │        │ │ Cache  │ │ Daemon │
   └────────┘ └────────┘ └────────┘

Components

Frontend

  • Technology: React 18+ with TypeScript
  • Build Tool: Vite
  • Styling: Tailwind CSS
  • State Management: React Query
  • Port: 5151 (development), embedded in backend (production)

Backend

  • Technology: Go 1.24+ with Gin framework
  • Database: PostgreSQL / MySQL / MongoDB (configurable)
  • Cache: Redis (optional)
  • Port: 8383
  • Features:
    • JWT authentication
    • Role-based access control (RBAC)
    • Docker management (containers, images, networks, volumes)
    • Multi-host support
    • Real-time updates via WebSocket
    • Audit logging

Database

  • Supported: PostgreSQL, MySQL(Default), MongoDB
  • ORM: GORM
  • Auto-migration: Yes

Cache

  • Technology: Redis
  • Optional: Yes (falls back to in-memory cache)
  • Use Cases: Session storage, API response caching

Deployment Modes

1. Docker Compose (Recommended)

# Generate configuration
./generate-passwords.sh  # Linux/macOS
.\generate-passwords.ps1  # Windows

# Start all services
docker compose up -d

Services:

  • mysql - MySQL 8 database
  • redis - Redis 7 cache
  • steerdock - Main application (frontend + backend)

2. Docker Container (Single Image)

# Build and run single container (requires external database)
docker build -t steerdock:latest .
docker run -d --name steerdock \
  -p 8383:8383 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e DATABASE_URL="mysql://user:pass@host:3306/db" \
  steerdock:latest

3. Development Mode

# Linux/macOS
./start-dev.sh

# Windows
.\start-dev.ps1

4. Production Mode

# Linux/macOS
./start-prod.sh

# Windows
.\start-prod.ps1

Why Monolithic?

SteerDock uses a monolithic architecture for the following reasons:

  1. Simplicity: Easier to develop, test, and deploy
  2. Performance: No inter-service communication overhead
  3. Resource Efficiency: Lower memory and CPU usage
  4. Easier Debugging: Single codebase, single process
  5. Faster Development: No need to manage multiple services

Directory Structure

steerdock/
├── backend/             # Go backend application
│   ├── config/          # Configuration files
│   ├── handlers/        # HTTP handlers
│   ├── middleware/      # Middleware (auth, CORS, etc.)
│   ├── models/          # Database models
│   ├── routes/          # API routes
│   └── main.go          # Entry point
├── frontend/            # React frontend application
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── pages/       # Page components
│   │   ├── hooks/       # Custom hooks
│   │   └── config/      # Configuration
│   └── package.json
├── sql/                 # Database initialization scripts
├── docker-compose.yml   # Docker Compose configuration
└── .env                 # Environment variables

API Structure

All API endpoints are served from the backend on port 8383:

/api/v1/
├── auth/              # Authentication
│   ├── login
│   ├── logout
│   └── refresh
├── containers/        # Container management
├── images/            # Image management
├── networks/          # Network management
├── volumes/           # Volume management
├── hosts/             # Docker host management
├── users/             # User management
└── system/            # System information

Configuration

All configuration is centralized in:

  • .env file (environment variables)

Generate configuration:

# Linux/macOS
./generate-passwords.sh

# Windows
.\generate-passwords.ps1

Scaling Considerations

While the current architecture is monolithic, it can be scaled:

  1. Horizontal Scaling: Run multiple backend instances behind a load balancer
  2. Database Scaling: Use read replicas, connection pooling
  3. Caching: Redis for session and API response caching
  4. CDN: Serve static frontend assets via CDN

Last Updated: January 2026