# Architecture Decision Records — Documenting the Why

<!-- hint:slides topic="ADRs: why decisions get lost, ADR structure and template, lifecycle, when to write vs skip" slides="4" -->

## Why Decisions Get Lost

Teams make dozens of architecture choices: database, framework, deployment model. Months later, nobody remembers *why* we chose PostgreSQL over MongoDB, or why we put the auth service in a separate repo. Knowledge lives in Slack, emails, and people's heads. New joiners repeat debates. Old decisions get "rediscovered" and overturned without context.

**ADRs fix that** by creating a durable record of the reasoning behind important choices.

## What Is an ADR?

An **Architecture Decision Record** (ADR) is a short, standalone document that captures a single architectural decision, the context that drove it, and the consequences. It answers: *What did we decide? Why? What are the tradeoffs?*

## Standard Format

A typical ADR has five sections:

| Section | Purpose |
|---------|---------|
| **Title** | Short, descriptive (e.g., "Use Redis for session storage") |
| **Status** | proposed, accepted, deprecated, superseded |
| **Context** | What forces, constraints, or options led to this decision? |
| **Decision** | What we decided — clear and actionable |
| **Consequences** | Positive and negative outcomes, follow-up work |

Example:

```markdown
# ADR-001: Use Redis for session storage

## Status
Accepted (2024-03-15)

## Context
We need shared session state across multiple app instances.
Options: in-memory (not shared), DB (slow), Redis (fast, shared).

## Decision
Use Redis with a 24h TTL for session storage.

## Consequences
- Positive: Fast, horizontally scalable
- Negative: Extra infra; need Redis HA in prod
- Follow-up: Set up Redis Sentinel
```

## When to Write One (and When Not To)

**Write when:**
- The decision affects multiple teams or services
- Reversing it would be costly
- Future developers will wonder "why did we do this?"

**Skip when:**
- Trivial or reversible (e.g., formatting style)
- Temporary workaround you'll fix next sprint
- Purely operational (restart policy) unless it has architectural impact

## Lightweight vs Heavyweight

- **Lightweight:** One file per decision, Markdown, in the repo. Fast to write.
- **Heavyweight:** Formal review, templates, tooling (e.g., Log4brains). Use when governance matters.

Most teams start lightweight and add structure if needed.

## ADR Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Proposed
    Proposed --> Accepted: Approved
    Proposed --> Rejected: Discarded
    Accepted --> Deprecated: No longer relevant
    Accepted --> Superseded: Replaced by new ADR
    Deprecated --> [*]
    Superseded --> [*]
```

| Status | Meaning |
|--------|---------|
| **Proposed** | Under discussion |
| **Accepted** | Active decision |
| **Deprecated** | No longer followed; not replaced |
| **Superseded** | Replaced by another ADR (link it) |

## Storing ADRs in the Repo

Common layout:

```
docs/adr/
  0001-use-redis-for-sessions.md
  0002-migrate-to-graphql.md
  0003-adopt-event-sourcing.md
```

Numbering preserves order. Some teams use dates: `2024-03-15-use-redis.md`.

## Tooling

- **adr-tools** — CLI to create, link, and supersede ADRs
- **Log4brains** — Web UI to browse and search ADRs; integrates with Git
- **template** — A simple Markdown template in the repo is often enough

## Common Pitfalls

| Pitfall | Fix |
|---------|-----|
| Writing too late | Write when you decide; memory fades fast |
| Too much detail | One decision per ADR; keep it 1–2 pages |
| Not linking to code | Add a line: "Implemented in `src/auth/session.js`" |
| No consequences | List at least one negative; honesty helps future readers |
| Never updating status | Deprecate or supersede when decisions change |

## Key Takeaways

- ADRs capture **why**, not just **what**
- One decision per record
- Store them in the repo; make them discoverable
- Update status when decisions change