Architecture Decision Records (ADRs): How to Write and Visualize Them (2026)

Architecture Decision Records (ADRs) are short documents that capture a significant architectural decision — what was decided, why, and what alternatives were considered. First popularized by Michael Nygard and the broader C4 model community, ADRs have become a standard practice in software teams that want to preserve institutional knowledge and make their architecture reviewable over time. In 2026, as systems grow more complex and AI assists more decisions, the case for structured ADRs is stronger than ever.

This guide explains what ADRs are, provides a practical template, and shows how to pair each ADR with a visual architecture diagram — so your team can understand not just what was decided but what the system looks like after the decision was made.

Why use Architecture Decision Records?

Every engineering team makes consequential architectural decisions: which database to use, whether to adopt a service mesh, how to handle authentication, whether to go monolith or microservices. Most of these decisions are made in Slack threads, video calls, or design review meetings — and then forgotten. Six months later, a new engineer asks "why did we use Kafka here instead of RabbitMQ?" and nobody can remember. ADRs solve this:

• Preserve context — record the trade-offs considered, not just the outcome
• Onboard faster — new engineers can read ADRs to understand why the system is shaped the way it is
• Prevent re-litigation — when someone proposes a change, you can reference the ADR that explains why the current approach was chosen
• Enable better reviews — ADRs give reviewers the context they need to evaluate a proposed change against the system's stated architectural principles
• Create an audit trail — in regulated environments (SOC 2, HIPAA, CMMC), ADRs document why security-relevant decisions were made

The standard ADR format

ADRs are intentionally short — typically one to two pages. The most widely adopted format has five sections:

• Title — a short noun phrase describing the decision. Use a number prefix for ordering: "ADR-0012: Use PostgreSQL as the primary database"
• Status — Proposed, Accepted, Deprecated, or Superseded by ADR-XXXX
• Context — the situation that requires a decision. What forces are at play? What constraints exist? Be factual, not opinionated.
• Decision — the chosen option, stated clearly. "We will use PostgreSQL as the primary relational database for all new services."
• Consequences — what becomes easier or harder as a result. Include positive and negative consequences honestly.

Some teams extend this with an Alternatives considered section that explicitly records options that were evaluated but rejected, with brief reasoning.

ADR template

# ADR-[NUMBER]: [Short title]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX

## Context
[What is the problem or situation requiring a decision?
What forces are at play — technical, team, cost, compliance?]

## Decision
[The chosen option, stated clearly in 1–3 sentences.]

## Alternatives considered
- **[Option A]** — [Why it was rejected]
- **[Option B]** — [Why it was rejected]

## Consequences
**Positive:**
- [Benefit 1]
- [Benefit 2]

**Negative / trade-offs:**
- [Trade-off 1]
- [Trade-off 2]

## Diagram
[Link to or embed the architecture diagram showing the system
after this decision is applied.]

Real ADR example: choosing a message queue

# ADR-0008: Use Apache Kafka for order event streaming

**Status:** Accepted

## Context
The Order Service needs to notify downstream services
(Inventory, Shipping, Analytics) when orders are created
or updated. Current synchronous API calls create tight
coupling and cause cascade failures when a downstream
service is slow or unavailable.

## Decision
We will use Apache Kafka as the message broker for order
domain events. OrderService publishes events; downstream
services subscribe to relevant topics.

## Alternatives considered
- **RabbitMQ** — Simpler setup and AMQP support, but
  lacks durable replay for late-joining consumers and
  doesn't scale to our projected event volume.
- **AWS SQS/SNS** — Managed and low-ops, but fan-out
  to multiple consumers requires SNS+SQS wiring that
  creates operational complexity without replay semantics.

## Consequences
Positive:
- Downstream services decouple from OrderService
- Consumers can replay events for debugging or backfill
- Scales to millions of events/day without re-architecture

Negative:
- Kafka cluster adds operational overhead
- Eventual consistency: downstream data may lag seconds

Adding a visual diagram to your ADR

Text ADRs answer why a decision was made. A companion architecture diagram answers what the system looks like after the decision. Together, they give future engineers everything they need to understand a significant change.

For ADR-0008 above, the companion diagram shows the order event flow after the decision:

Where to store ADRs

ADRs should live in version control alongside your code, not in Confluence or Notion where they'll be detached from the system they describe. The most common convention:

• Create a docs/adr/ directory in your repository
• Name files sequentially: 0001-use-postgresql.md, 0002-adopt-kubernetes.md
• Never delete or modify accepted ADRs — instead, create a new ADR that supersedes the old one and update the old ADR's status field
• Store companion diagrams as Mermaid code blocks in the ADR Markdown file itself, or as linked draw.io XML files in the same directory

ADR anti-patterns to avoid

• Writing ADRs after the fact — ADRs written long after a decision is made tend to rationalize rather than explain. Write them during the decision process.
• Capturing everything — not every technical choice needs an ADR. Reserve them for decisions with long-lasting consequences: data model choices, service boundaries, auth architecture, third-party vendor selection.
• Storing in Confluence without linking to the code — documentation that isn't near the code it describes quickly becomes stale and unfindable.
• No diagram — a text ADR without a diagram forces the reader to hold the entire system in their head. Even a simple before/after diagram dramatically improves comprehension.

Generating ADR companion diagrams with AI

The most common friction with ADR diagrams is the time cost: drawing a complete architecture diagram to accompany every ADR feels heavyweight. AI generation removes that friction. A well-written ADR context section contains enough information to generate the companion diagram in seconds:

Related guides: writing a software architecture document, how to document software architecture, and C4 model architecture diagrams.