diff --git a/decisions/README.md b/decisions/README.md new file mode 100644 index 0000000..8ef89ea --- /dev/null +++ b/decisions/README.md @@ -0,0 +1,36 @@ +# 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](0001-paleta-complementaria.md) | Complementary palette over classic LCARS | accepted | +| [0002](0002-jerarquia-tiers.md) | Tier hierarchy: Router / Cell / Core / Hub | accepted | +| [0003](0003-mqtt-como-espina-dorsal.md) | MQTT as the spine of the system | accepted | +| [0004](0004-gitops-como-source-of-truth.md) | GitOps as the source of truth | accepted | +| [0005](0005-sovereignty-vs-hyperscaler.md) | Sovereignty over hyperscaler convenience | accepted | +| [0006](0006-router-sirve-shell-ui.md) | Router serves console shell, Cell provides APIs | accepted | +| [0007](0007-evidence-chain-postpone.md) | Evidence chain is separate workstream, not blocking demo | accepted | +| [0008](0008-retencion-30d-default-argentina.md) | Default 30-day retention for Argentina | accepted | +| [0009](0009-no-redundancia-titulos.md) | No redundant titles in UI (rail + topbar + ctx-strip) | accepted | +| [0010](0010-synopsis-como-landing.md) | SYNOPSIS as the landing view | 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.