Architecture Decision Records (ADRs)
This directory holds the canonical record of major architectural decisions made on TwoMore.
What is an ADR?
A short (1-2 page) document that captures a single architectural decision: the context, the options considered, the choice made, and the consequences. ADRs are immutable once accepted — to revise a decision, write a new ADR that supersedes the old one.
The purpose: provide future contributors (human and AI) with the why behind decisions that may seem strange in retrospect. Code shows what; ADRs show why.
Format
Each ADR is a markdown file: NNNN-short-title.md where NNNN is a sequential number.
Use the template as the starting point.
Status values
- Proposed — under discussion
- Accepted — adopted; binding
- Superseded by NNNN — replaced by another ADR
- Deprecated — no longer applies, but not directly replaced
Index
| ADR | Title | Status |
|---|---|---|
| 0001 | Agentic project foundation — 9-layer infrastructure | Accepted |
| 0002 | Hexagonal architecture for shared business logic | Accepted |
| 0003 | Tamagui as the sole styling solution | Accepted |
| 0004 | Supabase as the managed backend | Accepted |
| 0005 | Network orchestration protocols (A–K) | Accepted |
| 0006 | ESLint ratchet: zero waivers as precondition | Accepted |
When to write an ADR
- Adopting a new framework or major library (Reanimated, MMKV, FlashList)
- Changing the dependency direction in the architecture
- Establishing a new directory convention
- Choosing between two roughly-equivalent technical paths
- Reversing a previous decision
When NOT to write an ADR
- Bug fixes
- Refactors that don't change architecture
- New screens or features
- Performance tuning within an established architecture