Architecture Decision Records
ADRs capture why a significant technical decision was made — the context, the choice, the alternatives weighed (with cost), and the consequences. Short, numbered, append-only (superseded rather than deleted), reviewed like code.
When to write one: any decision that is costly to reverse, affects multiple teams/clients, or that someone will later ask "why did we do it this way?" — landing-zone shape, auth model, data residency, tooling standards, platform choices.
Log
This is the internal log. Customer-specific ADRs live in their space — e.g. Novamera decisions. Follow-up ADRs nest under the decision they refine (see the sidebar).
| ADR | Title | Status | Date |
|---|---|---|---|
| 0001 | Internal Developer Documentation & ADR Platform | TBD | 2026-07-17 |
| 0001.1 | ↳ Crawl — Static Documentation Site (MVP hosting) | TBD | 2026-07-17 |
| 0002 | Zero-Trust Access Perimeter for *.propellabs.io |
TBD | 2026-07-17 |
| 0003 | Central Observability — Query-in-Place, Ingestion Opt-in | TBD | 2026-07-20 |
Format
Each ADR leads with a value-first line (outcome + value + cost) — the build renders it as a "Why this matters" hero, because an ADR has to sell its decision to reviewers and future readers, not just record it. Then: Context · Decision · Consequences · Alternatives (with cost) · Discussion. Copy ADR-0001 as the template. Statuses: TBD (suggested) → Accepted → (Deprecated | Superseded by ADR-NNNN).
Numbering: top-level decisions are sequential — 0001, 0002, … A follow-up that refines a parent is numbered PARENT.N — 0001.1, 0001.2, … — so a parent's children stay contiguous no matter how many unrelated ADRs land in between. Children Refine: ADR-NNNN and nest in the nav.