# 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.