Architecture Decision Records (ADRs)

An ADR captures a significant technical decision: the context that forced a choice, the decision made, and the consequences accepted. They exist so that a year from now (or a new engineer, or an AI assistant) can understand why the system is the way it is — not just what it does.

Format

Each ADR follows the same shape:

• Status — accepted / superseded / proposed
• Context — the forces and constraints at play
• Decision — what was chosen
• Consequences — what this buys us and what it costs
• Alternatives considered — what we didn’t pick, and why

Index

These ADRs were reconstructed from the codebase and project history to document decisions already in force. Where a decision is still evolving, the Status says so.