A living log of significant architecture decisions. Each decision is captured once, dated, and never edited after acceptance — superseding decisions are added as new entries that reference the old one.
What is the problem, force, or constraint that demands a decision? Include business drivers, technical constraints, and any prior commitments. Keep it factual — no advocacy yet.
Decision
State the decision in one or two sentences, in the active voice: “We will …”. Be specific enough that a new engineer can act on it without asking.
Drivers
#
Driver
Type
1
<e.g. RTO ≤ 15 min>
Business / NFR
2
<e.g. existing PostgreSQL operational expertise>
Capability
3
<e.g. SOC 2 audit logging requirement>
Compliance
Options considered
#
Option
Summary
Verdict
A
<option name>
One-line description
Chosen / Rejected
B
<option name>
One-line description
Rejected — <reason>
C
<option name>
One-line description
Rejected — <reason>
Consequences
Type
Consequence
Positive
<what gets easier / better / cheaper>
Positive
<…>
Negative
<what gets harder / riskier / more expensive>
Negative
<…>
Neutral
<side effects worth recording>
Risks & mitigations
Risk
Likelihood
Impact
Mitigation
Owner
<risk>
L/M/H
L/M/H
<action>
<name>
Compliance & security notes
Call out anything relevant to audit, data classification, regulatory scope (GDPR, SOX, NIS2, etc.), threat model changes, or controls affected. Leave the section in even if empty — write “None identified” — so future readers know it was considered.
<link to design doc, RFC, ticket, vendor docs, related ADRs>
<link to meeting notes if the decision was made in a forum>
3. Worked example
ADR-0002 — Adopt OAuth 2.1 with PKCE for all first-party clients
Field
Value
Status
Accepted
Date
2026-02-03
Decider(s)
A. Architect, Security Guild
Consulted
Mobile lead, Web platform lead, IAM team
Informed
All product teams
Supersedes
—
Superseded by
—
Tags
identity, security, auth
Context
Our existing first-party clients (web, iOS, Android, desktop) authenticate against the IdP using a mix of OAuth 2.0 implicit flow, authorization code without PKCE, and one legacy resource-owner password grant. The implicit flow is deprecated by the OAuth 2.1 draft, the password grant fails our zero-trust posture review, and the inconsistency makes our SOC 2 control narrative hard to write.
Decision
We will standardise on OAuth 2.1 with PKCE (S256) for all first-party clients — web, native, and desktop — and retire the implicit and password grants by Q3 2026.
Drivers
#
Driver
Type
1
Align with OAuth 2.1 best current practice
Standards
2
Remove password handling from non-IdP code paths
Security
3
Single auth pattern simplifies SOC 2 evidence
Compliance
4
Reduce per-client auth implementations from 3 to 1
Maintainability
Options considered
#
Option
Summary
Verdict
A
OAuth 2.1 + PKCE everywhere
Single pattern, IdP-hosted login
Chosen
B
Keep code-flow for web, PKCE for native only
Less disruption
Rejected — preserves two patterns, complicates audit
C
Move to SAML for web
Reuses corporate SSO
Rejected — poor fit for SPA / mobile, increases scope
Consequences
Type
Consequence
Positive
One auth pattern across all clients; simpler threat model.
Positive
Password handling removed from app code; reduced phishing surface.
Positive
Audit evidence collapses to one flow diagram.
Negative
Legacy desktop client requires a system-browser refactor (≈ 3 sprints).
Negative
Short-lived breakage risk for offline-first mobile features during migration.
Neutral
Token lifetime policy must be revisited (separate ADR).
Risks & mitigations
Risk
Likelihood
Impact
Mitigation
Owner
Desktop refactor slips past Q3
M
M
Phased rollout; keep legacy grant gated behind feature flag with hard cut-off date.
Desktop lead
Mobile users logged out en masse at cutover
L
H
Dual-issue tokens for a 30-day overlap window.
IAM team
Compliance & security notes
Removes ROPC grant, closing finding SEC-2025-014. Aligns with NIST SP 800-63B AAL2 for first-party access. No change to data classification handling. Threat model updated to remove “credential interception in client code” branch.
Implementation notes
Epic: IAM-1187
Cut-off date for legacy grants: 2026-09-30
Feature flag: auth.legacy_grants_enabled
Runbook: <link>
References
OAuth 2.1 draft (IETF)
Internal threat model v3.2
SOC 2 control CC6.1 mapping
4. House rules
Rule
Why
One decision per ADR.
Keeps the log searchable and reversible.
Never edit an Accepted ADR’s Decision or Context.
The log is a history, not a wiki page. Add a superseding ADR instead.
Status changes are allowed and dated in the log index.
