This page describes the runtime architecture of a StreamSpace deployment. For the full technical reference (CRDs, sequence diagrams, security boundaries) see docs/ARCHITECTURE.md in the main repo.

┌──────────────────────────────────────────────────────────────┐
│ Control Plane (single deployment, multi-pod) │
│ ┌────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ Web UI │ │ API (Gin) │ │ Agent WebSocket Hub │ │
│ └────────┘ │ REST + WS │ │ Heartbeats, commands, │ │
│ │ │ │ status updates │ │
│ │ Selkies │ └──────────────────────────┘ │
│ │ HTTP/WebRTC │ │
│ │ Proxy │ ┌──────────────────────────┐ │
│ └──────────────┘ │ PostgreSQL (sessions, │ │
│ │ │ users, templates) │ │
│ │ └──────────────────────────┘ │
└─────────────────────┼────────────────────────────────────────┘
 │ WebSocket (wss://)
 ┌───────┴───────┐
 ▼ ▼
 ┌──────────┐ ┌──────────┐
 │ K8s Agent│ │ Docker Ag│
 └────┬─────┘ └────┬─────┘
 │ │
 ▼ ▼
 ┌─────────┐ ┌─────────┐
 │ Session │ │ Session │
 │ Pod │ │ Container│
 │ Selkies │ │ Selkies │
 │ :8080 │ │ :8080 │
 └─────────┘ └─────────┘

• Auth — JWT issuance/refresh, MFA, SSO bridges (SAML/OIDC/OAuth2)
• Session orchestration — CRUD on Session resources, dispatching commands to the right agent based on the session's chosen platform
• Agent WebSocket Hub — bidirectional channel: control plane → agent (commands), agent → control plane (heartbeats, status, lifecycle events)
• Selkies HTTP/WebRTC proxy — /api/v1/http/<session-id>/ validates the bearer token, looks up the session's in-cluster Service, and reverse-proxies to the Selkies endpoint on port 8080
• Multi-tenancy — every request is org-scoped via JWT claims; cross-tenant access is rejected at the handler

• Watches a Session CRD for new sessions, materializes them into Deployment/Service/PVC
• Manages the session lifecycle: create, hibernate, wake, terminate
• Reports back via the WebSocket Hub: streamingReady once the Selkies endpoint is up
• Leader election for HA (multi-replica deployment)

• Equivalent of the K8s Agent for Docker hosts
• HA via swappable backend: file, Redis, or Docker Swarm

• React + TypeScript + Material-UI
• Embeds the Selkies stream via <iframe src="/api/v1/http/<session-id>/?token=...">
• Admin pages: users, agents, plugins, templates, audit log, monitoring

• PostgreSQL — single source of truth for sessions, users, templates, tokens, audit events
• Redis — optional, used by the Agent Hub when the control plane runs multi-pod (for cross-pod agent routing)

1. User opens session in the UI
2. UI requests /api/v1/http/<session>/?token=<jwt>
3. API validates the token, looks up the session's in-cluster Service
4. API reverse-proxies the HTTP request to the session pod (Selkies UI assets)
5. Browser establishes a WebRTC peer connection (signaling through the proxy)
6. Once connected, video/audio/input flow browser ↔ pod directly via WebRTC

The control plane never sees raw video frames. Its job is auth, signaling, and asset delivery.

• Control Plane — multi-pod deployment behind a load balancer with sticky sessions (required for the WebSocket hub and the Selkies signaling channel)
• K8s Agent — multi-replica with leader election; only one acts on commands, others stand by
• Docker Agent — file/Redis/Swarm backend selectable per environment
• Database — standard PostgreSQL HA (your provider of choice)

• Browser ↔ API — TLS-enforced ingress, JWT-authenticated, rate-limited
• API ↔ Agent — outbound WebSocket from agent (firewall-friendly), API key or mTLS authentication
• API ↔ Session pod — in-cluster only; the Selkies proxy never exposes a session's address externally
• Network policies — sessions cannot reach each other or the control plane unless explicitly allowed

• docs/ARCHITECTURE.md — the full technical doc
• docs/design/architecture/ — ADRs (decision records)
• docs/historical/ — frozen v2 snapshots, including the original V2_ARCHITECTURE.md