Architecture Decision Records (ADR)

ADR = Architecture Decision Record

ADRs document significant architectural decisions, their context, and consequences. Unlike RFCs (which propose changes), ADRs record decisions that have been made.

When to Write an ADR

Write an ADR when you:

• Choose between competing technologies
• Define a pattern that others should follow
• Make a decision that constrains future options
• Establish a convention that's not obvious

Examples:

• "Use Litestar instead of FastAPI"
• "Implement Repository pattern with explicit session passing"
• "Choose NATS over Redis for job queue"
• "Adopt CloudEvents format for domain events"

ADR Format

We use the MADR (Markdown Any Decision Records) format:

docs/adr/
├── 0001-use-litestar-as-web-framework.md
├── 0002-explicit-unit-of-work.md
├── 0003-pydantic-for-doctype-schemas.md
└── ...

ADR Template

See adr-template.md.

ADR Lifecycle

┌──────────┐     ┌────────────┐     ┌────────────┐
│ Proposed │ ──► │  Accepted  │ ──► │ Deprecated │
└──────────┘     └────────────┘     └────────────┘
                       │                   │
                       ▼                   ▼
                 ┌────────────┐     ┌─────────────┐
                 │ Superseded │ ◄── │ Superseded  │
                 │   by XXXX  │     │   by XXXX   │
                 └────────────┘     └─────────────┘

Status	Meaning
Proposed	Under discussion
Accepted	Approved and in effect
Deprecated	No longer recommended but still documented
Superseded	Replaced by a newer ADR

ADR vs RFC

Aspect	RFC	ADR
Purpose	Propose a change	Record a decision
Timing	Before implementation	During/after decision
Approval	Requires TSC vote	Author discretion (review welcome)
Length	Detailed, includes alternatives	Concise, focused on rationale

Guidelines

Do

• Write ADRs close to when decisions are made
• Include the "why" — context matters for future readers
• Reference related ADRs and RFCs
• Update status when decisions change

Don't

• Write ADRs for trivial decisions
• Remove or delete old ADRs (mark as superseded instead)
• Include implementation details (that goes in code/docs)

Existing ADRs

The project may have ADRs in various locations. Consolidate to:

docs/adr/XXXX-title.md

Creating an ADR

# Copy template
cp docs/processes/adr-template.md docs/adr/0000-your-decision.md

# Assign next number
# Edit content
# Open PR or commit directly (for non-controversial decisions)