2.2 KiB
2.2 KiB
Architecture Decision Records
This folder contains lightweight ADRs (Architecture Decision Records) for the major design choices made during the initial design phase of the Blocao platform.
Conventions
- Numbered sequentially:
0001-,0002-, ... - Filename slug describes the decision in 3-5 words.
- Status is one of:
proposed,accepted,superseded by NNNN,deprecated. - ADRs are never edited after acceptance — superseding decisions get a new number.
- Each ADR has: Context (why this came up), Decision (what we chose), Consequences (good and bad), Alternatives considered.
Index
| # | Title | Status |
|---|---|---|
| 0001 | Complementary palette over classic LCARS | accepted |
| 0002 | Tier hierarchy: Router / Cell / Core / Hub | accepted |
| 0003 | MQTT as the spine of the system | accepted |
| 0004 | GitOps as the source of truth | accepted |
| 0005 | Sovereignty over hyperscaler convenience | accepted |
| 0006 | Router serves console shell, Cell provides APIs | accepted |
| 0007 | Evidence chain is separate workstream, not blocking demo | accepted |
| 0008 | Default 30-day retention for Argentina | accepted |
| 0009 | No redundant titles in UI (rail + topbar + ctx-strip) | accepted |
| 0010 | SYNOPSIS as the landing view | accepted |
| 0011 | Communication & transparency (build in public, layered) | accepted |
When to write a new ADR
Write a new ADR whenever:
- A choice between two or more reasonable alternatives is made and the choice will affect future work.
- A decision is non-obvious enough that someone joining the project later will ask "why did they do it this way?".
- The decision will be expensive to reverse.
Don't write ADRs for trivial preferences (variable naming, file location, formatting). Those go in docs/03-design/ if relevant.