Canonical Sources¶
One home per concept. This is the successor to the PRD's §0.3 and the linchpin of the whole site:
it is the single place that records which page each concept — and each legacy §-number — now lives on.
When a concept appears in multiple places, the page below is authoritative; everything else is a
cross-reference. Arrived with a bare §24.1 or FR-065? Find its new home here in one hop.
The anchor convention (why old §-links keep working)
Every section keeps a §-encoded anchor that is independent of its page and its title:
§N.M→#section-N-M·§24B.3→#section-24b-3FR-065→#fr-065·SC-016→#sc-016
A link target is therefore page-path + stable anchor. If a section is ever re-homed to a
different page, only this table changes — the anchor does not. mkdocs build --strict fails the
build on any broken §-link, so drift can't sneak in.
Concept → canonical home¶
| Concept | § |
Page |
|---|---|---|
| Component names / metaphors | §1 | Overview › Naming & Components |
| System topology & cluster layout | §2, §4 | Overview › System Topology · Cluster Topology |
| Anatomy of a deploy | §0.2 | Overview › Anatomy of a Deploy |
| Control plane (Starbase) | §8–§14 | Starbase |
| Build system (Starforge / Depot / Railpack) | §16 | Starforge |
| Cluster agent (Shuttle) | §17–§31 | Shuttle |
| Tenant identity key | §24.1 | Shuttle › Labels |
| Resource labels | §24 | Shuttle › Labels |
| Resource annotations | §24B | Shuttle › Annotations |
| HTTPRoute naming (metrics attribution) | §20.2 | Shuttle › Per-Project Resources |
| Shuttle ↔ Starbase contract | §25 (payload §25.1) | Shuttle › API Contract |
| Desired state (the spine) | §32 | Starbase › Desired State |
| RBAC & permissions | §15 | Starbase › RBAC |
| Env vars & secrets (Var Groups) | §38 | Starbase › Var Groups |
| Security & tenant isolation | synthesis | Shuttle › Security & Isolation |
| Networking (VPC/IP, gateway, LB) | §4.4, §5, §33, §34 | Networking |
| Observability (logs + metrics + platform; self-contained build/operate guide) | §35 | Observability |
| Billing flow | §36 | Billing |
| Functional requirements / success criteria | §40 | FR · SC |
| Open / not-yet-designed work | §39 | Reference › Open Work |
Full § → page directory¶
Every authored section, in order. The legacy §-numbering is preserved as the anchor.
Overview (Part 0–1)¶
§ |
Title | Page |
|---|---|---|
| §0.1 | What Starform Is | overview |
| §0.2 | Anatomy of a Deploy | overview/02 |
| §0.3 | Canonical Sources | reference/canonical-sources |
| §0.4 | MVP Scope at a Glance | overview/03 |
| §1 | Naming System + Pod Tiers | overview/04 |
| §2 | System Overview | overview/05 |
| §3 | Binaries & Repos | overview/06 |
| §4 / §4.1–4.3 | Cluster Topology | overview/07 |
| §4.4 | VPC & IP Topology | networking/02 |
| §5 | Traffic Flow | networking/01 |
| §6 | Tech Stack Summary | overview/08 |
| §7 | Scaling Model | overview/09 |
Starbase & Starforge (Part 2)¶
§ |
Title | Page |
|---|---|---|
| §8 | Starbase Overview | starbase |
| §9 | Package Layout | starbase/02 |
| §10 | Ports Detail | starbase/03 |
| §11 | Integrations Detail | starbase/04 |
| §12 | Region Registry | starbase/05 |
| §13 | API Binary | starbase/06 |
| §14 | Worker Binary | starbase/07 |
| §15 / §15.1–15.11 | RBAC & Permissions | starbase/rbac |
| §16 / §16.1–16.2 | Starforge Overview & Flow | starbase/starforge/01 |
| §16.3–16.5 | BuildService & Frontend | starbase/starforge/02 |
| §16.6–16.7 | Logs & Billing | starbase/starforge/03 |
| §16.8–16.10 | Limitations & Migration | starbase/starforge/04 |
| §16.11 | Git Integration & Webhooks | starbase/starforge/05 |
| §16.12 | Build Lifecycle & UX | starbase/starforge/06 |
Shuttle (Part 3)¶
§ |
Title | Page |
|---|---|---|
| §17 / §18 | Overview & Goals / Non-Goals | shuttle |
| §19 / §19.1–19.5 | Architecture | shuttle/02 |
| §20 / §20.1–20.6 | Per-Project Resources | shuttle/03 |
| §21 | Repo Structure | shuttle/04 |
| §22 | Shuttle RBAC | shuttle/05 |
| §23 | Configuration | shuttle/06 |
| §24 / §24.1–24.4 | Label Conventions | shuttle/07 |
| §24B / §24B.1–24B.9 | Annotation Conventions | shuttle/08 |
| §25 / §25.1–25.3 | Shuttle ↔ Starbase Contract | shuttle/09 |
| §26 / §26.1–26.3 | Shuttle Observability | shuttle/10 |
| §27 | Failure Modes | shuttle/11 |
| §28 | Resource Requirements | shuttle/12 |
| §29 | Scaffolding | shuttle/13 |
| §30 | Success Criteria | shuttle/14 |
| §31 | Future Enhancements | shuttle/15 |
Cross-Cutting (Part 4)¶
§ |
Title | Page |
|---|---|---|
| §32 | Desired State Model | starbase/desired-state |
| §33 / §33.1–33.3 | Gateway Architecture | networking/03 |
| §34 / §34.1–34.3 | Load Balancer Lifecycle | networking/04 |
| §35.1 | Customer Logs | observability/03-logs |
| §35.2 | Customer Metrics | observability/02-metrics |
| §35.3 | Shuttle's Role | observability/01-architecture |
| §35.4 | Telemetry Transport | observability/04-transport |
| §35.5 | Platform Self-Monitoring | observability/05-platform-self-monitoring |
| §36 / §36.1–36.3 | Billing Flow | starbase/billing |
| §37 | BYOC (out of scope) | starbase/byoc-portability |
| §38 / §38.1–38.8 | Var Groups | starbase/var-groups |
Reference (Part 5)¶
§ |
Title | Page |
|---|---|---|
| §39 / §39.1–39.3 | Not Yet Designed | reference/open-work |
| §40.1 | Functional Requirements (FR-001…071) | reference/functional-requirements |
| §40.2 | Success Criteria (SC-001…018) | reference/success-criteria |
| §41 | Document History | reference/document-history |
Cross-document dependency rule¶
Companion material references canonical pages by anchor; the self-contained SRE Implementation Guide is the one scoped exception — it restates observability contracts inline (with provenance tags), and the canonical page wins on conflict. This mirrors CLAUDE.md §6. If a companion needs something shared-but-different, extend the canonical page rather than forking the concept.