Starbase¶
Starbase is the central control plane of the Starform platform — a Go monolith with two binaries (API + Worker) sharing one module, one codebase, and one database. It decides what should run; Shuttle applies it. It follows ports & adapters (hexagonal architecture) for cloud infrastructure, and a separate integrations pattern for services that run simultaneously.
Two binaries, one module:
| Binary | Entry Point | Execution Model | Purpose |
|---|---|---|---|
| Starbase API | cmd/api/main.go | Request-response (fast) | Dashboard API, Shuttle endpoints, Git webhooks, Stripe webhooks, auth, sessions |
| Starbase Worker | cmd/worker/main.go | Background jobs (slow) | Build orchestration, cluster provisioning, DB provisioning, billing cron, cleanup jobs |
Both share the same internal/ packages, same database, same types. They just have different entry
points that register different handlers.
Critical rule
internal/core/ imports only from internal/port/ and internal/integration/ interfaces.
Never from internal/adapter/, internal/store/, or any external SDK directly.
Everything Starbase owns lives under this tab — the ports and integrations, the region registry and
Region Onboarding flow (region-onboarding), the
API and Worker binaries, the RBAC model (§15), the build system Starforge (§16, a
BuildService port inside the Worker), and the Billing flow (§36, the Worker billing cron).
How to build Starbase — the sidebar is the plan¶
The sidebar groups are build layers, in order:
- Orientation — read first, build nothing (package layout, the two binaries).
- Foundation — data model → services → auth → RBAC → Dashboard API. Milestone: sign in, create workspace/project/environment/service — nothing deploys yet.
- Wiring — ports & adapters, integrations, region registry, desired state. Milestone: a cluster can pull a correct desired-state payload.
- Features — Starforge, Var Groups, Managed Databases, Billing. Each is an end-to-end slice; Starforge first (it completes push → build → deploy → live URL).
- Operate & Reference — runbooks (region onboarding), not code.
Layers, not a strict waterfall: some Foundation work reaches forward (Auth's SSO flow uses the §11 integrations; the API's deploy endpoints come alive only with Starforge). Build the layer's milestone, not 100% of its pages, before moving on.
Every page owns its own tables and API endpoints; the Data Model and Dashboard API pages are pure maps.
Cross-references
Package layout → §9 · ports → §10 · integrations → §11 · region registry → §12 · API binary → §13 · Worker binary → §14 · RBAC → §15 · build system → Starforge §16 · billing → §36. The "Starbase decides, Shuttle applies" principle lives in Desired State (§32).