Architecture Decision Records
Architecture Decision Records (ADRs) capture architectural decisions along with their context and consequences. They provide a historical record of why decisions were made, not just what was decided.
Why ADRs?
ADRs help us:
- Remember context - Why did we choose this approach 6 months ago?
- Onboard new team members - Understand the reasoning behind the decisions
- Avoid repeated discussions - Reference past decisions
- Track evolution - See how architecture changes over time
ADR Format (MADR)
We use the following format:
markdown
# ADR-NNN: [Title]
## Status
`Proposed` | `Accepted` | `Deprecated` | `Superseded` by [ADR-XXX](./xxx-title.md)
## Context
[Describe the context and problem statement]
## Decision
[Describe the decision and rationale]
## Consequences
### Positive
- [Consequence 1]
- [Consequence 2]
### Negative
- [Consequence 1]
- [Consequence 2]
### Risks
- [Risk 1]: [Mitigation]
## Related
- [Link to related ADR or documentation]Keep ADRs focused on one decision
Each ADR should address one decision. If you find yourself making multiple decisions, split them into separate ADRs.
Don't modify accepted ADRs
Once accepted, ADRs are immutable. If a decision changes, create a new ADR that supersedes the old one. This preserves the historical record.
Creating New ADRs
- Copy the template above
- Create file:
NNN-kebab-case-title.md - Fill in all sections
- Submit PR for review
- Update the decision log below
Decision Log
| ADR | Title | Status | Date |
|---|---|---|---|
| 001 | Microservices Architecture | Accepted | 2026-02 |
| 002 | Mutation Naming | Accepted | 2026-02 |
| 003 | Mailing Address Schema | Accepted | 2026-03 |
| 004 | GraphQL Mutation Error Handling | Accepted | 2026-03 |
| 005 | Message Queue | Accepted | 2026-04 |
| 006 | Document Pathname Field | Accepted | 2026-06 |
| 007 | Hybrid Sanity Match Catalog | Accepted | 2026-07 |