lockstep
6 min readNaman Jain

Architecture decision record examples: 6 ADRs you can copy

Six architecture decision record examples: database, API, frontend, infrastructure, security, and a superseded decision, plus a real public ADR from Backstage.

A new engineer asks why the service uses Postgres for its job queue instead of a message broker. Two people remember a meeting; neither remembers the reasons. The team re-debates it for an hour and lands, again, on Postgres. An ADR would have taken ten minutes to write and two to read.

These examples follow the format Michael Nygard proposed in Documenting Architecture Decisions: title, status, context, decision, consequences. The first five are illustrative; the last section points to a real public ADR. For a blank template and other formats such as MADR, see the ADR template.

1. Database: Postgres as the job queue

# ADR 012: Use Postgres for background jobs instead of a message broker

Status: Accepted, 2026-03-04
Deciders: Arjun (eng lead), Priya (platform)

## Context
We run about 20,000 background jobs a day: emails, exports, webhooks.
We already operate Postgres. Adding a broker means another system to
run, monitor, and back up, for a two-person platform team.

## Decision
We will run background jobs from a Postgres table using row locking
(SELECT ... FOR UPDATE SKIP LOCKED), through an existing job library.

## Consequences
- No new infrastructure; jobs are backed up with the database.
- Jobs and data can change in one transaction.
- Throughput is limited by the database. Revisit above roughly
  500,000 jobs a day, or if job load affects query latency.
- No fan-out to multiple consumers; add a broker if we need it.

2. API: versioning in the URL

# ADR 018: Version the public API in the URL path

Status: Accepted, 2026-05-20

## Context
Enterprise customers pin integrations for months. We need breaking
changes without breaking them. Options: URL path (/v2/), a header,
or date-based versions.

## Decision
Public API versions go in the path, starting with /v2/. A version is
supported for at least 12 months after its successor ships.

## Consequences
- Easy for customers to see and test; works with any HTTP client.
- Two versions of some handlers in the codebase during overlap.
- Header and date-based versioning rejected as harder for customers
  to debug.

3. Frontend: named exports only

# ADR 007: Use named exports, not default exports

Status: Accepted, 2026-01-12

## Context
Default exports let each importer choose a name, so the same
component appears under different names across the codebase.
Refactoring and search tools work less well.

## Decision
Modules use named exports. Default exports only where a framework
requires them, such as lazy-loaded route components.

## Consequences
- Rename and find-references work reliably.
- A lint rule enforces it; existing files migrate when touched.

4. Infrastructure: one region first

# ADR 021: Run in a single region until a customer requires more

Status: Accepted, 2026-06-02

## Context
Multi-region adds replication, failover testing, and cost. No current
customer contract requires it. Two prospects asked about data residency.

## Decision
Production runs in one region, with backups copied to a second region.
We will add a region when a signed contract requires it.

## Consequences
- Lower cost and simpler operations.
- A regional outage means downtime; recovery target is 4 hours.
- Data residency deals need a new ADR before signing.

5. Security: short-lived tokens

# ADR 024: Access tokens expire after 15 minutes

Status: Accepted, 2026-07-15
Deciders: Sam (security), Arjun

## Context
Leaked long-lived tokens were the root cause in a security review
finding. Refresh tokens are already supported by our auth library.

## Decision
Access tokens expire after 15 minutes. Refresh tokens last 30 days,
rotate on each use, and are revoked on password change.

## Consequences
- A leaked access token is useful for minutes, not days.
- Clients must handle refresh; the mobile app needs an update first.
- More calls to the auth service; capacity reviewed and sufficient.

6. A decision that replaces another

When a decision changes, write a new ADR and mark the old one. Don't edit the old decision.

# ADR 031: Move background jobs to a message broker

Status: Accepted, 2026-11-03
Supersedes: ADR 012

## Context
Jobs reached 650,000 a day after the webhooks launch, above the
threshold ADR 012 set. Job polling now shows up in database latency.

## Decision
New job types use the managed message broker. Existing Postgres jobs
migrate by end of Q1.

## Consequences
- Database load drops; jobs scale separately.
- A new system to monitor; on-call runbook updated.
- Jobs and data no longer change in one transaction; use the outbox
  pattern where that matters.

And in ADR 012, only the status changes:

Status: Superseded by ADR 031, 2026-11-03

A real one: Backstage ADR003

The open-source Backstage project, created at Spotify, keeps its ADRs in docs/architecture-decisions. ADR003, on avoiding default exports, is a good model: its context explains how module conventions changed and lists the problems with default exports; its decision is a single sentence with a stated exception; and it closes with the consequences. Example 3 above is a shorter take on the same idea.

What the good ones share

  • The title is the decision, not the topic. "Use Postgres for background jobs," not "Job queue."
  • The context explains the pressure, with numbers where possible.
  • The decision is one or two sentences, in active voice.
  • Consequences include the costs, and often a condition for revisiting.
  • History is kept. Old ADRs are superseded, not edited.

Where ADRs fall short

ADRs work when someone writes them. Most architecture decisions are made in a pull request thread or a Slack huddle, and the ADR never gets written. And an ADR in docs/adr/ doesn't reach the engineer, or the AI coding agent, editing the job runner today unless they go looking. See ADRs for AI coding agents.

Where Lockstep fits

Lockstep captures decisions where they're made, in PRDs, Slack, and pull requests, drafts the record, and routes it to its owner for approval. Approved decisions brief the Claude Code sessions working on the affected code, and a new decision supersedes the old one with both kept visible.

See how it works.

Sources checked 16 November 2026

For a blank template and the MADR and Y-statement formats, see the ADR template. For ADRs versus decision logs, see decision log vs ADR. For the larger design an ADR may belong to, see the technical design document template. For learning from incidents, see the blameless postmortem template. For when to write an ADR instead of an RFC or design doc, see ADR vs RFC vs design doc vs PRD. For API decisions worth an ADR, see API design best practices.

Frequently asked questions

What does a good ADR example look like?
One page or less, with a title stating the decision, a status, the context that forced a choice, the decision itself in active voice, and the consequences, including the downsides. It records one decision. Anything longer usually belongs in a design doc that the ADR links to.
Where can I find real ADR examples?
Many open-source projects publish their ADRs. Backstage keeps its ADRs in docs/architecture-decisions in its GitHub repository; ADR003, on avoiding default exports, is a clear short example. Searching GitHub for a docs/adr or doc/adr folder finds many more.
How do I write an ADR that replaces an old one?
Write a new ADR with the new decision, set its status to Accepted, and say which ADR it supersedes. Then change the old ADR's status to Superseded by the new one. Don't edit the old decision's text; the history is part of the value.
What should go in the consequences section?
Everything that becomes easier or harder because of the decision: new constraints, work that's now required, risks, and what you gave up. An ADR that lists only benefits isn't being honest about the trade-off.
How many ADRs should a project have?
One per decision that's hard to reverse or that people will later ask about. Small, easily changed choices don't need one. A busy team might write a few a month.

Keep reading