Skip to content

System Topology

Core principle: Starbase decides, Shuttle applies. Everything flows through desired state.

The system has three planes: a single control-plane region that decides what runs, one or more regions each holding customer clusters plus an off-cluster telemetry tier, and an external Grafana Cloud plane that watches Starform itself.

Starbase decides · Shuttle applies — everything flows through desired state Source & edge Developer · Git repogit push CloudflareCDN · DNS · WAF · TLS edge DO Load Balancerper region Control-plane region · one region at MVP Starbase APIdecides what runs · query broker Starbase Workerbuilds · billing cron Stardeckdashboard DO PostgresStarbase DB DO Registryapp images Customer cluster · one or more per region Shuttleapplies desired state Customer workloadsyour pods Envoy GatewayHTTPRoute · L7 metrics vmagentscrapes metrics Fluent Bitlogs · DaemonSet Grafana Alloyplatform agent metrics-server+ kube-state-metrics Regional telemetry · DO VM droplets · private VPC VictoriaMetricscustomer metrics Vector aggregatorregional log fan-in ClickHouselogs + billing audit External SaaS Depotbuild · remote BuildKit Tigrisobject storage Stripepayments Grafana Cloudplatform self-monitoring push pull desired state · 30s traffic metrics logs platform

Diagram — system topology. A single control-plane region (Starbase API + Worker, Stardeck, DO Managed Postgres, DO Container Registry) decides what runs. Each region holds one or more customer clusters — Shuttle, Envoy Gateway, customer workloads, and the vmagent / Fluent Bit / Grafana Alloy / metrics-server + kube-state-metrics agents — plus an off-cluster telemetry tier on DO VM droplets (Vector aggregator, ClickHouse, VictoriaMetrics). The spine is "Starbase decides, Shuttle applies" — Shuttle pulls desired state every 30s and reconciles the cluster to match. A push builds on Depot → image to the Registry → the Worker updates desired state; Cloudflare → DO Load Balancer → Envoy routes traffic; vmagent → VictoriaMetrics (metrics) and Fluent Bit → Vector → ClickHouse (logs) carry telemetry; Grafana Alloy ships platform series to Grafana Cloud. Starbase also reads each region's stores (through the server-side tenant filter) to render dashboards. Blue = desired-state / metrics · amber = logs · gray = traffic · dashed = external/platform.

Legend (matches the SVG color legend, CLAUDE.md §5)

Brand blue = Starform-built (Starbase API/Worker, Stardeck, Shuttle) · gray = third-party · dashed = data store / external SaaS. The diagram is theme-aware — toggle light/dark in the header and it re-colors. Click it to zoom.