Skip to content

System Topology

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

The system spans two VPCs: a single Control-plane VPC that decides what runs (Starbase, Stardeck, Postgres, Registry), and a Regional VPC /16 per region holding the customer cluster plus an off-cluster telemetry tier — joined by private VPC peering (one per region; the VPCs are separate even at single-region MVP). An external Grafana Cloud plane 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 VPC · central · its own VPC (peered to each regional VPC) Starbase APIdecides what runs · query broker Starbase Workerbuilds · billing cron Stardeckdashboard DO PostgresStarbase DB DO Registryapp images private VPC peering · telemetry read (1/region) Regional VPC /16 · one per region — customer cluster + regional droplets Customer cluster · self-managed Talos + gVisor · per region Shuttleapplies desired state Customer workloadsgVisor-sandboxed pods Envoy GatewayHTTPRoute · L7 metrics OTel Collectortelemetry agent · DaemonSet Grafana Alloyplatform agent metrics-server+ kube-state-metrics Regional droplets · DO VMs — telemetry + ops/jump OTel gatewaybatches · sole writer ClickHouselogs + metrics · plan-based TTL Shipyardjump droplet · post-MVP External SaaS Depotbuild · remote BuildKit Tigrisobject storage · post-MVP Stripepayments Grafana Cloudplatform self-monitoring push pull desired state · 30s traffic logs + metrics platform

Diagram — system topology. The Control-plane VPC (Starbase API + Worker, Stardeck, DO Managed Postgres, DO Container Registry — registries are per region) decides what runs; it is its own VPC, central at MVP. Each region is a Regional VPC /16 holding one or more customer clusters — self-managed Talos + gVisor — running Shuttle, Envoy Gateway, gVisor-sandboxed customer workloads, and the OTel Collector / Grafana Alloy / metrics-server + kube-state-metrics agents — plus, in the same VPC, an off-cluster telemetry droplet on a DO VM (ClickHouse and the regional OTel Collector gateway; post-MVP the Shipyard machine-lifecycle agent lands on the region's ops/jump droplet). The control-plane and regional VPCs are always separate, joined by private VPC peering — one per region, even at single-region MVP. 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; the OTel Collector agent ships app logs, Envoy access logs, and cAdvisor metrics to the regional OTel gateway → ClickHouse within the regional VPC; Grafana Alloy ships platform series to Grafana Cloud. Starbase reads each region's store over the peering (through the server-side tenant filter) to render dashboards. Blue = desired-state / telemetry · 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.