Skip to content

Architecture

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

Architecture

StreamSpace is designed as a Kubernetes-native control plane with three deployable services and custom resources that describe workspaces. Use this page alongside docs/ARCHITECTURE.md, docs/PHASE2_ARCHITECTURE.md, and docs/VNC_MIGRATION.md.

Component Stack

  • Controller (controller/): Kubebuilder operator that reconciles Session and Template CRDs, provisions PVCs, manages idle detection and hibernation, and exposes metrics via /metrics. It runs with restricted PodSecurity and RBAC scoped to the streamspace namespace.
  • API (api/): Gin-based REST/WebSocket service that handles auth flows (local, OIDC, SAML via Authentik/Keycloak), proxies VNC traffic, emits audit logs, enforces rate limiting, handles webhook signatures, and backs the UI and CLI.
  • UI (ui/): React + Vite SPA served via Nginx/Node, offering the end-user catalog, session viewer, admin console, compliance dashboards, and plugin marketplace. It communicates with the API via REST/WebSocket and can embed VNC or pop out sessions.
  • Worker Sessions: Pods created from templates (LinuxServer.io images today, TigerVNC/noVNC migration tracked for Phase 6). Each mounts per-user PVCs, runs with read-only root filesystems, and exposes ports (default 3000 VNC proxy) to the controller ingress.

Data Flow

  1. Template Sync: Template repos (streamspace-templates or custom Git) are synced by the controller, creating/updating Template CRDs.
  2. User Action: UI/API requests create Session CRDs referencing a template and user.
  3. Controller Reconcile: Controller provisions PVCs, applies secure pod templates, sets quotas, labels pods for monitoring, and updates status (Running/Hibernated/Terminated).
  4. Streaming: API establishes VNC/WebSocket channels between browser and session pod, enforcing authentication and rate limits.
  5. Hibernation: Metrics + idle timers trigger scale-to-zero; resume requests wake the deployment and restore session state.

Supporting Infrastructure

  • Helm Chart (chart/): Deploys controller, API, UI, Postgres (optional), ingress, network policies, and monitoring sidecars.
  • Manifests (manifests/): CRDs, RBAC, network policies, secure pod templates, and config samples for operators outside Helm.
  • Terraform (terraform/): Infrastructure-as-code samples for provisioning clusters, storage, and supporting services.
  • Monitoring: Prometheus scrapes controller/API, Grafana dashboards (docs/monitoring), and optional metrics-exporter plugin.

Refer to Deployment-and-Operations for environment-specific layouts and Templates-Catalog / Plugins-Catalog for extension-specific architecture.

Clone this wiki locally