Skip to content

Architecture

Jump to bottom
joshuaaferguson edited this page Nov 28, 2025 · 3 revisions

Architecture

Version: v2.0-beta.1

StreamSpace v2.0 uses a Control Plane + Agent architecture for multi-platform support. This page covers the v2.0 architecture alongside docs/ARCHITECTURE.md and docs/V2_ARCHITECTURE.md.

v2.0 Architecture Overview

┌─────────────┐         ┌──────────────────────────────────┐
│   Web UI    │────────▶│       Control Plane (API)        │
│  (React)    │  REST/WS│  • Agent Hub (WebSocket)         │
└─────────────┘         │  • Command Dispatcher            │
                        │  • VNC Proxy (end-to-end)        │
                        │  • Multi-Tenancy (org-scoped)    │
                        └────────────┬─────────────────────┘
                                     │ WebSocket (wss://)
                        ┌────────────┴────────────┐
                        │                         │
                   ┌────▼─────┐             ┌────▼─────┐
                   │ K8s Agent│             │Docker Agt│
                   │ (~80%)   │             │ (~60%)   │
                   └────┬─────┘             └────┬─────┘
                        │                        │
                   ┌────▼────┐              ┌───▼────┐
                   │   K8s   │              │ Docker │
                   │ Cluster │              │  Host  │
                   └─────────┘              └────────┘

Component Stack

Control Plane (api/)

  • Agent Hub: WebSocket server managing agent connections
  • Command Dispatcher: Routes commands to appropriate agents
  • VNC Proxy: End-to-end VNC tunneling (<100ms latency)
  • Multi-Tenancy: Org-scoped access control with JWT claims
  • Observability: 3 Grafana dashboards, 12 Prometheus alerts
  • API Documentation: OpenAPI 3.0 with Swagger UI at /api/docs

Platform Agents

  • K8s Agent (agents/k8s-agent/): Production-ready Kubernetes agent (~80% coverage)

    • Session lifecycle management (create, hibernate, terminate)
    • VNC tunnel management
    • Leader election for HA (3-10 replicas)
    • Automatic failover (<5s)

  • Docker Agent (agents/docker-agent/): Production-ready Docker agent (~60% coverage)

    • Docker and Docker Compose support
    • HA backends: File, Redis, Swarm
    • Agent reconnection (~23s)

Web UI (ui/)

  • React + TypeScript with Material-UI
  • Real-time agent monitoring via WebSocket
  • 98% test passing (189/191 tests)
  • Admin dashboard with org-scoped views

Data Flow (v2.0)

  1. Agent Registration: Agents connect to Control Plane via WebSocket and register their capabilities
  2. User Action: UI/API creates session request with org context
  3. Command Dispatch: Control Plane routes command to appropriate agent
  4. Session Provisioning: Agent provisions session on target platform (K8s pod or Docker container)
  5. VNC Streaming: VNC traffic tunneled through Control Plane to agent to session
  6. Hibernation: Configurable idle timeout triggers scale-to-zero

High Availability

Component HA Mechanism Failover Time
Control Plane API Multi-pod (2-10 replicas) <5s
K8s Agent Leader election <5s
Docker Agent File/Redis/Swarm backends <5s

Observability

Grafana Dashboards

  • Control Plane: API latency, error rates, request volume
  • Sessions: Active sessions, lifecycle, resources
  • Agents: Heartbeat, command latency, capacity

Prometheus Alerts

  • API Latency: Warning >800ms, Critical >2s
  • Session Startup: Warning >30s, Critical >60s
  • Agent Heartbeat: Warning >60s, Critical >120s
  • Error Rate: Warning >1%, Critical >5%

Refer to Deployment-and-Operations for deployment guides and Roadmap-and-Releases for version history.

Clone this wiki locally