Glossary¶
The load-bearing terminology. Match these terms verbatim — don't introduce parallel vocabulary (CLAUDE.md §7). Each term links to its canonical home.
Identity & tenancy¶
Tenant key — project_id + environment + service_id. Every customer metric and log line is
attributed to this tuple. workspace_id rides along as the billing-boundary label, not part of
the key. There is no customer_id (removed in v1.9) and no customers table.
→ §24.1
Entity hierarchy — workspace → project (pinned to exactly one cluster at creation) →
environment (customer-named, validated RFC 1123 ≤30 chars — no fixed dev/staging/prod enum;
flags is_protected, is_ephemeral) → service (web / worker / cron) · database · bucket ·
var_group. → §15, FR-070
Ephemeral / preview environment — identified by the structural is_ephemeral flag, not by
name-matching. Keys the per-route preview-metric suppression. → FR-067
The 8 load-bearing labels¶
A Shuttle-created resource missing a required one is a bug (full catalog §24):
starform.io/managed-by (=shuttle, primary Informer filter) · workspace-id · project-id ·
environment · service-id · service-name · cluster-id · var-group-id (on Secrets) · tier.
→ §24.1
Components (the star metaphor)¶
| Term | Meaning | Home |
|---|---|---|
| Starform | The product — the developer PaaS | Overview |
| Starbase | Control plane — Go monolith, two binaries (API + Worker); decides what should run | Starbase |
| Shuttle | Per-cluster Go agent; makes each cluster match desired state | Shuttle |
| Starforge | Build pipeline (a BuildService port inside Starbase Worker; Depot + Railpack) |
Starforge |
| Stardeck | Next.js customer dashboard | Stardeck |
| Mission Control | Bird's-eye observability view inside Stardeck | Stardeck |
| Mininova → Ultranova | Customer-facing pod instance sizes (Nova tiers) | §1 |
Naming conventions¶
- Namespace:
proj-<project_slug>→ §20.1 - Var Group Secret:
vg-<var_group_id>→ §38 - HTTPRoute:
<project_uuid><service_uuid>-<environment>— each UUID hyphen-stripped to 32 hex chars; positional parsechars[0:32]=project,[32:64]=service, post-hyphen=environment. Load-bearing for metrics attribution. → §20.2
Enumerations¶
The 7 customer metrics — latency, RPS, throughput, error rate, CPU, memory, network. → §35.2
Build states — pending → building → built → deploying → deployed (terminal: failed,
cancelled). → §16.12
Status tags (→ custom admonitions) — [MVP] (!!! mvp) · [Post-MVP] (!!! post-mvp) ·
pre-launch-blocking (!!! pre-launch) · out of scope (!!! out-of-scope) · Decision pending
(!!! decision-pending).
Vendors / adapters (MVP)¶
Cloud = DigitalOcean (DOKS, Managed Postgres, Managed Valkey, Container Registry, Load Balancer, VPC peering, Droplets) · builds = Depot + Railpack · object storage = Tigris · DNS/CDN/WAF = Cloudflare · payments = Stripe · logs = ClickHouse · metrics = VictoriaMetrics · collection = Fluent Bit + Vector + vmagent + Grafana Alloy · platform monitoring = Grafana Cloud (MVP-only). → Tech Stack