ADRs make decision-making auditable, transparent, and repeatable. Each ADR captures a single architectural choice, its context, options, rationale, and consequences.
1. What is an Architectural Decision Record (ADR)?
An ADR records the design choice, context, forces (constraints/goals), options considered, and the rationale for the final choice.
Purpose
- Context for New Team Members: Explain why the system is built a certain way.
- Prevents Rework: Avoids re-litigating the same decisions years later.
- Auditability: Permanent record for debugging systemic issues and post-mortems.
- Enforces Consensus: Documents trade-offs and stakeholder agreement.
2. The Standard ADR Template Structure
Commonly used Michael Nygard-style format. Adapt as needed, but keep entries concise.
A. Title
A concise, active-voice title (e.g., “Use Kafka for Asynchronous Communication”).
B. Status
- Proposed — under discussion
- Accepted — approved and being implemented
- Superseded — replaced by a new ADR (cite it)
- Deprecated — no longer relevant
C. Context
Problem description and forces leading to the decision.
Example: Replace a centralized DB with a distributed store to handle 10Ă— read growth; payments need near-real-time consistency.
D. Decision
Clear statement of the chosen design.
Example: Use Amazon DynamoDB for User Profiles with an AP consistency model.
E. Alternatives Considered
- PostgreSQL + Read Replicas (Rejected): Doesn’t scale linearly; replication lag unacceptable.
- MongoDB Atlas (Rejected): Licensing costs exceed budget.
F. Consequences (Trade-offs)
- Positive: Scalable throughput; lower ops overhead.
- Negative: Eventual consistency; potential vendor lock-in.
3. ADRs vs. Design Documents
| Feature | ADR (Architectural Decision Record) | Design Document (HLD/LLD) |
|---|---|---|
| Scope | Single, significant architectural choice. | Detailed blueprint of how the system works. |
| Focus | Why the decision was made (rationale, trade-offs). | How it will be implemented. |
| Format | Short (1–2 pages), immutable record. | Longer, living document updated during development. |
4. Lifecycle and Governance
- Placement: Keep ADRs in the repo (e.g.,
docs/arch/) near the code. - Immutability: Accepted ADRs are immutable; changes are new ADRs marked “Superseded”.
ADR Status Over Time
Example timeline of ADRs per month by status (stacked bars). Adjust data to your project.