Starbase Package Layout¶
The package tree below is the canonical layout for the Starbase module. The dependency rule is
enforced by directory: internal/core/ is pure business logic and imports only port and integration
interfaces — never an adapter, store, or external SDK (§8).
Starbase package tree · starbase/
starbase/
├── cmd/
│ ├── api/main.go # Wires ports, integrations, starts HTTP server
│ └── worker/main.go # Wires ports, integrations, starts job consumer
│
├── internal/
│ ├── core/ # Pure business logic — NO cloud/vendor imports
│ │ ├── project/ # Project lifecycle (create, delete, settings)
│ │ ├── service/ # Service CRUD, desired state computation
│ │ ├── deploy/ # Deployment orchestration, placement decisions
│ │ ├── billing/ # Billing aggregation, invoice generation logic
│ │ ├── cluster/ # Cluster placement decisions, capacity management
│ │ └── build/ # Build orchestration logic (trigger, status, rollback)
│ │
│ ├── port/ # Interfaces — swappable, one active per region
│ │ ├── cloud.go # ClusterProvider, DatabaseProvider, CacheProvider
│ │ ├── registry.go # RegistryProvider
│ │ ├── storage.go # StorageProvider
│ │ ├── dns.go # DNSProvider
│ │ ├── payment.go # PaymentProvider
│ │ ├── build.go # BuildService
│ │ └── queue.go # JobQueue
│ │
│ ├── integration/ # Interfaces + implementations — all active simultaneously
│ │ ├── git.go # GitProvider interface
│ │ ├── sso.go # SSOProvider interface
│ │ ├── github/ # Implements GitProvider + SSOProvider
│ │ │ ├── git.go
│ │ │ └── sso.go
│ │ ├── gitlab/ # Implements GitProvider + SSOProvider
│ │ │ ├── git.go
│ │ │ └── sso.go
│ │ ├── bitbucket/ # Implements GitProvider + SSOProvider
│ │ │ ├── git.go
│ │ │ └── sso.go
│ │ └── google/ # Implements SSOProvider only
│ │ └── sso.go
│ │
│ ├── adapter/ # Port implementations — one active per region
│ │ ├── digitalocean/ # MVP adapters
│ │ │ ├── cluster.go # DOKS provisioning, node pool management
│ │ │ ├── database.go # Managed Postgres provisioning, resize, PITR
│ │ │ ├── registry.go # Container Registry
│ │ │ └── cache.go # Managed Valkey
│ │ ├── aws/ # Future — EKS, RDS, ECR, S3, ElastiCache
│ │ ├── gcp/ # Future — GKE, Cloud SQL, Artifact Registry, GCS, Memorystore
│ │ ├── tigris/ # Object storage (StorageProvider adapter, Partner Integration API)
│ │ ├── cloudflare/ # DNS management (shared across all regions)
│ │ ├── stripe/ # Payment (shared across all regions)
│ │ └── depot/ # Depot SaaS (Railpack + Dockerfile fallback, BuildService adapter)
│ │
│ ├── region/ # Region registry — maps region IDs to adapter sets
│ │ └── registry.go
│ │
│ ├── api/ # HTTP handlers (thin layer, calls core)
│ │ ├── dashboard.go # Dashboard REST API
│ │ ├── shuttle.go # Shuttle endpoints (desired state, snapshots, capacity)
│ │ ├── webhooks.go # Git provider + Stripe webhooks
│ │ └── middleware.go # Auth, logging, rate limiting
│ │
│ ├── worker/ # Job handlers (thin layer, calls core)
│ │ ├── build.go # Build job handler
│ │ ├── provision.go # Cluster + DB provisioning handler
│ │ ├── billing.go # Monthly billing aggregation
│ │ └── cleanup.go # Orphan resource cleanup, expired trials
│ │
│ └── store/ # Database access layer (Postgres, sqlc-generated)
│ ├── project.go
│ ├── environment.go # Environments (per-project; tenant-key component)
│ ├── service.go
│ ├── cluster.go
│ ├── user.go
│ ├── deployment.go
│ ├── var_group.go # var_groups, var_group_entries, service_var_groups (Section 38)
│ ├── bucket.go # Object storage buckets (Tigris primitive)
│ └── billing.go