Skip to content

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.