Architecture Decision Records (ADR)
Why and how to record architecture decisions, ADR templates (Nygard, MADR), lifecycle, where to store them, and examples.
What an ADR is
An ADR captures one significant decision: the context, the decision, the options considered and the consequences. Michael Nygard popularized the format in 2011. ADRs are short, immutable once accepted (superseded rather than edited), and stored close to the code or in an architecture repository.
Generate one with the ADR Generator.
What deserves an ADR
Decisions that are hard to reverse, affect quality attributes, cross team boundaries, or will be questioned later: choice of database, messaging pattern, cloud service, authentication approach, multi-tenancy model, API versioning policy.
Template (MADR-style)
# ADR-014: Use the transactional outbox for publishing domain events
- Status: Accepted
- Date: 2026-11-10
- Deciders: Order team, solution architect
## Context
Order and payment services publish events to Kafka. Dual writes (DB then Kafka) lost events
twice last quarter when the broker was unavailable after the DB commit.
## Decision drivers
- No lost or phantom events
- Minimal latency impact
- Works with PostgreSQL and our Kafka platform
## Considered options
1. Transactional outbox + Debezium CDC
2. Kafka transactions with DB (not atomic across systems)
3. Event sourcing with Kafka as source of truth
## Decision
Option 1. Write events to an outbox table in the same transaction; Debezium publishes them.
## Consequences
+ Atomic state change and event publication
+ Replayable from the outbox
- Extra infrastructure (Kafka Connect) to operate
- Consumers must be idempotent (at-least-once delivery)Lifecycle
Proposed → Accepted → (Deprecated | Superseded by ADR-NNN). Never rewrite history; add a new ADR that supersedes the old one.
Where to keep them
- In the service repo (
/docs/adr) for service-level decisions (tools: adr-tools, Log4brains). - In an architecture repository/wiki for cross-cutting and enterprise decisions, linked from affected repos.
Interview questions and answers
Why are ADRs valuable for an enterprise architect?
They create an auditable trail of reasoning, speed up onboarding, prevent relitigating settled decisions, and make governance lightweight: reviewers read ADRs instead of long documents.
What makes a bad ADR?
No real alternatives considered, missing context (why now), vague consequences, or recording trivial decisions that add noise.