Architecture & System Design

An overview of how TurboV orchestrates deployments, manages server state, and routes production traffic.

High-Level Design Principles

TurboV is designed to give you a modern PaaS developer experience while keeping 100% of your source code, databases, and customer traffic on your own infrastructure:

  1. Strict Control Plane vs Data Plane Separation: The TurboV control plane orchestrates deployments, schedules jobs, and manages metadata. Your servers execute your workloads independently. If the control plane is undergoing maintenance or temporarily unreachable, your running web applications and databases continue serving production traffic without interruption.
  2. Authoritative State vs Asynchronous Execution: User commands (such as clicking "Restart" or "Redeploy") are treated as intent. The control plane records the intent and dispatches a command with a unique correlation ID to the agent running on your server. State transitions (RUNNING, STOPPED, ERROR) are confirmed only after the agent verifies that the container has started and passed its health check.
  3. Zero Inbound Attack Surface: The TurboV Agent initiates an outbound, authenticated WebSocket connection to the control plane. You do not need to open SSH ports or custom agent ports on your firewall.

System Topology

+---------------------------------------------------------------------------------------+
|                                  TURBOV PLATFORM                                      |
|                                                                                       |
|  +--------------------+     +---------------------+     +--------------------------+  |
|  |  TurboV Dashboard  | --> |  Control Plane API  | --> |  Authoritative State DB  |  |
|  |  (Web Interface)   |     |  (Orchestrator)     |     |  (Configuration Store)   |  |
|  +--------------------+     +---------------------+     +--------------------------+  |
|                                        |                              |               |
|                                        v                              v               |
|                             +---------------------+     +--------------------------+  |
|                             |  WebSocket Gateway  |     |  Envelope Encryption     |  |
|                             |  (Agent Dispatcher) |     |  (Key Management Engine) |  |
|                             +---------------------+     +--------------------------+  |
+---------------------------------------------------------------------------------------+
                                         ^
                                         | Outbound Secure WSS (Encrypted Session)
                                         v
+---------------------------------------------------------------------------------------+
|                               YOUR HOST SERVER (VPS)                                  |
|                                                                                       |
|  +---------------------------------------------------------------------------------+  |
|  | TurboV Agent Daemon (systemd: turbov-agent.service)                             |  |
|  |   - Path Resolver: /opt/turbov (bin), /var/lib/turbov (data), /var/log/turbov   |  |
|  |   - Local Task Engine: deployment runner, database manager, health monitor      |  |
|  |   - Dynamic Traefik Router Configurator: /var/lib/turbov/traefik/dynamic/       |  |
|  +---------------------------------------------------------------------------------+  |
|                                        |                                              |
|                                        v                                              |
|  +---------------------------------------------------------------------------------+  |
|  | Docker Engine & Isolated Bridge Network: turbov                                 |  |
|  |                                                                                 |  |
|  |   [ Traefik v3 Reverse Proxy ] (turbov-traefik)                                 |  |
|  |     - Listening: Ports 80 & 443                                                 |  |
|  |     - ACME Let's Encrypt automated SSL: acme.json (chmod 0600)                  |  |
|  |     - Fallback Container: turbov-fallback (zero-downtime maintenance display)   |  |
|  |                                                                                 |  |
|  |   [ Your Application Containers ]                                               |  |
|  |     - Web Services (Internal bridge ports, zero-downtime routing)               |  |
|  |     - Worker Services (Background queues)                                       |  |
|  |     - Cron Containers (Scheduled tasks)                                         |  |
|  |                                                                                 |  |
|  |   [ Managed Database Containers ]                                               |  |
|  |     - PostgreSQL, MySQL, Redis, MongoDB                                         |  |
|  |     - Persistent Storage Volumes: vol_<database_id>                             |  |
|  +---------------------------------------------------------------------------------+  |
+---------------------------------------------------------------------------------------+

Action Flow Mechanism & Reliability

All lifecycle actions follow a verified correlation pattern:

sequenceDiagram
    autonumber
    actor User as Developer / Dashboard
    participant ControlPlane as TurboV Control Plane
    participant Agent as TurboV Agent (Host)
    participant Docker as Docker Daemon
 
    User->>ControlPlane: Click "Restart App"
    ControlPlane->>ControlPlane: Validate permissions & record intent (logId: act_101)
    ControlPlane->>Agent: Send command event { action: "restart", appId: "app_1", logId: "act_101" }
    Agent->>Docker: Execute container restart
    Docker-->>Agent: Container restarted & healthy
    Agent->>ControlPlane: Report status confirmation { appId: "app_1", status: "RUNNING", logId: "act_101" }
    ControlPlane->>ControlPlane: Update authoritative state to RUNNING
    ControlPlane-->>User: Live status reflects RUNNING in real time

Crash Safety & Reconciliation

If an agent temporarily disconnects due to a host reboot or network drop:

  • The control plane monitors pending commands and marks them timed out after a safe window, preventing stuck states.
  • When the host reconnects, the agent performs a state reconciliation check, reporting the true current status of all running containers.

Reverse Proxy & Edge Traffic Routing

TurboV bundles Traefik v3 (traefik:v3.3.4) on your server to handle public web traffic:

  • Dynamic Hot-Reloading: When a new deployment becomes healthy, the agent writes a routing manifest to /var/lib/turbov/traefik/dynamic/. Traefik updates its in-memory routing tables within milliseconds without restarting or dropping active connections.
  • Automated SSL Certificates: Traefik automatically contacts Let's Encrypt, completes the HTTP-01 challenge on port 80, stores the certificate in /var/lib/turbov/traefik/acme.json, and serves secure HTTPS traffic on port 443.
  • Maintenance Fallback: If an application is undergoing a cold reboot or temporary restart, requests are seamlessly routed to a local fallback container serving a clean status page rather than a browser timeout.

Security & Encryption Model

All sensitive application data is protected using enterprise-grade envelope encryption:

  1. A central Key Encryption Key (KEK) is maintained in an enterprise Key Management Service.
  2. Each project and environment generates an isolated 256-bit Data Encryption Key (DEK).
  3. Secrets and environment variables are encrypted using AES-256-GCM before being saved to storage.
  4. Secrets are decrypted into memory only during runtime container startup—they are never written into Docker image layers or build caches.