Architecture Decision Records (ADR)

Short, focused records of why we made key architectural decisions.

ADRs complement the existing guides and domain docs:

Guides & domain docs → how things work and how to use them
ADRs → why we chose this approach over alternatives

Current ADRs

When to add a new ADR

Create or update an ADR when you:

Introduce a non-trivial architectural change
Make a decision that will be hard to reverse later
Need to capture trade-offs or rejected alternatives

Keep ADRs short:

1–2 paragraphs of context
A clear decision statement
Key consequences (good and bad)
Links to relevant guides/domains