Architecture spine — decision → ADR → block → code¶
| Field | Value |
|---|---|
| Status | Draft (added 2026-04-30 as the prerequisite to Block 31 doc IA reorganization) |
| Audience | New contributor, returning contributor, assessor, partner reviewer |
| Goal | One page from "what is this part of the system?" to "where does it live?" — scannable in <2 minutes |
How to use this doc¶
CLAUDE.md is the index of what's loaded into the system today. The ADR INDEX is the granular log of every load-bearing decision. This document is the layer between — the architectural spine: ~15 decision themes, each pointing at one or two anchor ADRs, the implementation block(s) tracking the work, and the load-bearing code paths.
When asking "where does X live?", start here. When the answer doesn't satisfy, follow the ADR or design-doc link. When the answer is "I don't know which area this falls in," skim the Theme column.
This doc is deliberately narrow. It is not a feature list. It does not cover every ADR. Sub-decisions live in their parent ADR; design specifics live in docs/design/ ; implementation status lives in ../project/. The spine is the orientation layer.
Update rule. When a new decision is load-bearing enough to be remembered by a returning contributor a year later, add a row. When a row's decision is superseded, mark the supersession in-place (don't delete) and link to the new anchor.
The spine — fifteen architectural themes¶
| # | Theme | Headline decision | Anchor ADR(s) | Implementation block(s) | Load-bearing code |
|---|---|---|---|---|---|
| 1 | Mesh substrate | Identity-routed P2P WireGuard via Netbird (forked when needed); rathole + Coturn + relay on VPS for ingress | ADR 0110 (license posture) | Block 1, Block 39 | ops/ansible/nethost-relay.yml, ops/ansible/relay-server.yml, terraform/modules/relay/ |
| 2 | Mgmt-plane HA | PostgreSQL 16 + Spock multi-master (active-active inter-site) + keepalived active-passive intra-site | ADR 0801 | Block 4, Block 7 | ops/postgres/spock/, ops/ansible/mgmt-host.yml |
| 3 | Per-site topology | A+B mgmt-plane pair per site, plus observability + storage | ADR 0826 | Block 7 | ops/ansible/mgmt-host.yml, docs/design/ha-multi-site.md |
| 4 | Relay data plane | Rust clean-room rewrite (kTLS + io_uring + shard-per-core), released as goat-relay/v0.1.0 and in service; it replaced the Go relay |
ADR 0709 | Block 33 | goat-relay-protocol/, goat-relay/, ops/goat-relay/, ops/ansible/roles/goat-relay/ |
| 5 | Universal data substrate | Zenoh as universal peer-interaction substrate (Phase 2 gated; named NATS-JetStream fallback); image built from source | ADR 0210, ADR 0500, ADR 0509, ADR 0708 | Block 11 | zenoh-plugins/, ops/zenoh/, ops/ansible/roles/zenoh/ |
| 6 | Identity architecture | Four-domain model: humans+services via Ory (Kratos+Hydra), machines via Netbird, workloads via SPIFFE Phase 3+ | ADR 0411, ADR 0412, ADR 0413 | Block 21 | ops/ansible/roles/ory/, ops/compose/mgmt-host/docker-compose.ory.yml, ops/mgmt-host-bootstrap/ |
| 7 | OS + hardware baseline | Ubuntu 24.04 LTS + LUKS on x86; L4T 22.04 + Ubuntu Pro FIPS+STIG on Jetson-class arm64 (Kairos rejected) | docs/design/os-baseline-and-luks.md | Block 6, Block 6D | ops/ansible/roles/ubuntu-pro-fips/, ops/ansible/roles/usg-stig/, ops/ansible/roles/luks-unlock/ |
| 8 | Crypto posture | Two distinct paths: intra-mesh real-PQ via Rosenpass (not FIPS); cross-boundary FIPS PQC via x86 boundary node + strongSwan + ML-KEM | docs/design/fips-pqc-path.md | Block 19 | docs/compliance/ (waivers) |
| 9 | Supply chain | Chainguard-first; base images named by role, public defaults from Chainguard's free catalogue, a private catalogue only in an environment's overlay (ADR 1220); Iron Bank not a trust signal (per-image audit only); license tier ladder Permissive > Weak > Strong > Network copyleft; SSPL/restrictive disqualified | ADR 0700, ADR 1220, ADR 0110, ADR 0111 | Block 13 | docs/project/chainguard-procurement.md, docs/project/license-audit-2026-04-27.md |
| 10 | Observability — three layers | (i) Prometheus metrics; (ii) wide-event OTLP → OpenObserve on MinIO; (iii) tamper-evident audit on MinIO Object Lock | ADR 0815, ADR 0822, ADR 0508, ADR 0811 | Block 27, Block 17D, Block 18G | zenoh-plugins/audit-logger/, ops/monitoring/ |
| 11 | Egress + microsegmentation + policy | 5-tier cascading egress (DNS / nftables / Squid / dante / time-bounded direct); per-site Go policy engine; Spock-replicated approval state; OIDC-abstract | ADR 0805, ADR 0806 | Block 17, Block 18 | docs/design/egress-proxy.md, docs/project/egress-proxy-implementation.md |
| 12 | Silent control plane — paused (ADR 1192): no goatnet runs it; entry is a public round-robin name on every relay | Outer wg-cp0 per relay; retire public mgmt DNS; bundle-carried per-relay endpoint + control-plane keys; Tailnet-Lock-style peer-key attestation Phase 3 |
ADR 0313, ADR 0314, ADR 0315 | Block 22, Block 22H | docs/design/offline-enrollment.md §11 (deferred to Phase 2 close-out) |
| 13 | Rapid adaptation with AI (Block 23 bones) | Agent-class peers + queryable-by-default + citation discipline + ephemeral lifecycle + mandatory data-dictionary + materialized lineage; minimal semantic layer (named platform commitment); broader big-platform shape refused | ADR 0512 | Block 23 | docs/design/ai-rapid-adaptation.md, docs/design/data-dictionary.md, docs/design/lineage.md, docs/design/tipper.md, docs/design/scout.md, zenoh-plugins/schema-enforcer/ |
| 14 | Mission partner sharing + WASM | Reserved release/<partner>/ namespace; bring-your-own-OIDC; per-partner WASM conditioning sandbox (Wasmtime, fuel/memory/wall-clock-bounded, no net/fs/env imports); offline-CA-rooted module signing |
ADR 0821, ADR 0513, ADR 0501 (still stands for in-house interceptors) | Block 26, Block 28 | docs/design/mission-partner-sharing.md, docs/design/wasm-conditioning-sandbox.md, docs/partner-templates/data-sharing-charter.md, ops/wasm-modules/reference/ (planned) |
| 15 | Theater-scale shape | Federation plane (small, fast-replicating, theater-wide identity/policy/schema/audit metadata) + site plane (locally scalable bulk payloads); GovCloud as federation participant, not centralizer | ADR 0215 (envelope), ADR 0216 (planes) | Phase 4+ trigger | docs/design/goat-net-scaling.md |
Cross-cutting posture¶
These are not architectural themes themselves — they constrain how every theme above is executed:
| Concern | Anchor | What it constrains |
|---|---|---|
| Concurrency governance | ADR 0006 | Multi-agent + human teaming; opt-in pickup discipline; track trailers on commits |
| Git collaboration | ADR 0109 | Trunk-based, signed commits, conventional-commit titles, squash-merge |
| License posture | ADR 0110, ADR 0111 | Apache-2.0 own code; tier ladder for deps; Tier-5 disqualified |
| Tech strategy — language boundary | ADR 0112 | Per-byte hot path → Rust; per-request control → Go; F-017 anchor evidence |
| Soak discipline | ADR 1008 | Required for stateful + replicated components; smoke 5 min / validation 2 h / canonical 72 h / long-haul 30 d |
| Load discipline | ADR 1012 | No measured ceiling = no production-ready claim |
| Findings register | ADR 1011, ../findings/INDEX.md |
External-system behavior we engineer around; F-NNN IDs, append-only |
| Measurements register | ADR 1012, ../measurements/INDEX.md |
Numbers + method + reproducibility; M-NNN IDs |
| Validation state | ../project/validation-state.md |
Single inventory of "what's tested, what's running, what's open" |
| Phase gates | ADR 1006, ADR 0509 | Phase 2 gate: 4 questions (incl. substrate-boundary abstraction test) |
| Fleet management | ADR 1109, fleet-management.md |
How intent reaches N nodes and how divergence is seen. Convergence is pulled; waves are per-site and never advance on unknown; every operation class declares transport / partition-mode / artifact class / blast unit. Designed-not-built |
Where common questions land¶
| Question | Spine row | First link |
|---|---|---|
| "Where does schema enforcement live?" | 13 | ai-rapid-adaptation.md §"Bones" → data-dictionary.md |
| "What's the auth model?" | 6 | ADR 0411 |
| "How does a peer get on the mesh?" | 1 + 12 | offline-enrollment.md (Phase 2A bundles) |
| "Why Rust here vs Go there?" | tech-strategy | ADR 0112 |
| "What replicates between sites?" | 2 + 15 | ADR 0801, ADR 0216 |
| "Where's the audit log of record?" | 10 | ADR 0811 |
| "How does a partner share data?" | 14 | ADR 0821 |
| "What gates Phase 3?" | 5 + phase-gates | ADR 0509 |
| "What does the relay do under load?" | 4 + load-discipline | ../measurements/INDEX.md M-001 / M-002 / M-003 |
| "How do I know every node is running what it should?" | fleet-management | fleet-management.md §4 (what exists) → environment-parity.md (config alignment) |
What this doc is not¶
- Not a complete decision list. Sub-decisions live in their parent ADR.
- Not an implementation plan. Block status lives in
../project/implementation-plan.md. - Not a runbook index. Operations procedures live in
../operations/. - Not a substitute for CLAUDE.md. CLAUDE.md is the index of "what's loaded today" and stays the primary onboarding pointer.
- Not Block 31. Block 31 is the broader IA reorganization; this doc is the prerequisite spine that reorganization will hang the rest of the docs from.