# Architecture Decision Log: [Solution, programme or domain name]

> Architecture decision log (ADL): the register of every significant
> architecture decision for one solution, programme or domain, one line
> per decision, with its status, owner, date, drivers and a link to the
> full decision record. It also tracks superseded decisions, pending
> decisions with the date by which they must be made, rejected proposals,
> waivers and dispensations, decision dependencies and the review
> cadence. It follows the practice of architecture decision records
> popularised by Michael Nygard (2011) and collected at adr.github.io, and
> treats decisions and their rationale as part of the architecture
> description in the sense of ISO/IEC/IEEE 42010:2022. Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Keep one log per solution or programme. Each decision has one row here
  and, when it is significant (section 2.4), one decision record in ADR
  (Full) (`architecture/adr-full`), MADR (`dev/madr`) or the lean ADR
  (`dev/adr`) format. The log is the index and the status board; the
  record holds the argument.
- Never delete a row. A reversed decision becomes Superseded and points
  to the decision that replaced it; a dropped proposal becomes Rejected
  or Withdrawn. The history is the value of the log.
- Add a decision to the pending list as soon as you know it must be
  made, with the latest date it can be made without blocking delivery.
  Most architecture escalations are late decisions, not bad ones.
- Review the log at a fixed cadence (section 12) and at every design
  review. The High-Level Design (`architecture/high-level-design`) and
  the Solution Architecture Document (`architecture/solution-architecture`)
  list decision IDs from this log instead of restating them.
- Deviations from enterprise principles or standards go in section 9 as
  waivers with an expiry, not as silent exceptions in a design.
-->

## Document control

<!-- Guidance: Identify the scope of the log and the forum that ratifies decisions. The log itself is a living document: bump the minor version at each review, the major version when the scope or decision rights change. -->

| Field | Value |
|---|---|
| Document ID | [ADL-001] |
| Scope | [Solution / Programme / Domain name] |
| Decision forum | [Design authority / Architecture review board / Technical design forum] |
| Record location | [Repository path, for example `docs/decisions/`] |
| Record format | [ADR (Full) / MADR 4.0.0 / Nygard ADR] |
| Version | [1.0] |
| Status | [Active / Closed] |
| Owner | [@lead-solution-architect] |
| Approvers/reviewers | [@enterprise-architect], [@engineering-lead], [@security-architect] |
| Last reviewed | YYYY-MM-DD |
| Next review | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |
| Classification | [Internal / Confidential] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Log owner | [@name] | [Submitted] | YYYY-MM-DD |
| Chair of the decision forum | [@name] | [Approve decision rights and process] | YYYY-MM-DD |
| Enterprise architecture | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 1.0 | YYYY-MM-DD | [@name] | Log opened with conventions and first decisions |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Review: ADR-007 accepted, ADR-001 superseded, WVR-001 renewed |
| 1.2 | YYYY-MM-DD | [@name] | *Example:* Review: two pending decisions added for release 2 |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Purpose and scope](#1-purpose-and-scope)
2. [Conventions](#2-conventions)
3. [Decision rights and roles](#3-decision-rights-and-roles)
4. [Decision log](#4-decision-log)
5. [Decision summaries](#5-decision-summaries)
6. [Superseded and deprecated decisions](#6-superseded-and-deprecated-decisions)
7. [Pending decisions](#7-pending-decisions)
8. [Rejected and withdrawn proposals](#8-rejected-and-withdrawn-proposals)
9. [Waivers and dispensations](#9-waivers-and-dispensations)
10. [Decision dependencies](#10-decision-dependencies)
11. [Traceability](#11-traceability)
12. [Review cadence and health metrics](#12-review-cadence-and-health-metrics)
13. [Decision process](#13-decision-process)
14. [Glossary and references](#14-glossary-and-references)

## 1. Purpose and scope

<!-- Guidance: Say which decisions belong here and which belong in an enterprise log or a team's own notes. Pitfall: a log so broad that it fills with trivia, or so narrow that cross-team decisions are lost. -->

### 1.1 Purpose

This log gives everyone working on [scope] one place to see what has been
decided, by whom, when and why, what is still open and what has been
reversed. It lets new team members, reviewers, auditors and the teams
that will run the solution understand the reasoning behind the
architecture without reconstructing it from meeting notes.

### 1.2 Scope

| In this log | Elsewhere |
|---|---|
| *Example:* Decisions that affect more than one component or team of the Order Hub | Decisions inside one component: the component team's LLD or its own ADR folder |
| *Example:* Technology choices, integration styles, data ownership, hosting and resilience patterns | Enterprise-wide standards: the enterprise decision log or Tech Radar (`architecture/tech-radar`) |
| *Example:* Deviations from enterprise principles for this solution (section 9) | Product and scope decisions: product backlog and change control |
| [Item] | [Where] |

## 2. Conventions

<!-- Guidance: Fix the ID format, the statuses, the categories and the significance test once. The significance test decides when a full record is required; publish it so that teams do not argue case by case. -->

### 2.1 Identifiers and fields

- Decision ID: `ADR-NNN`, numbered in order of creation, never reused.
- Waiver ID: `WVR-NNN`. Pending decisions keep their `ADR-NNN` from the
  moment they are logged as Proposed.
- Each row carries: ID, title in active voice ("Use X for Y"), category,
  level, status, decision date, owner, deciders, drivers (requirement,
  principle or risk IDs), affected elements, record link and review date.

### 2.2 Statuses

| Status | Meaning | Allowed next status |
|---|---|---|
| Proposed | Raised and being analysed; has a need-by date | Accepted, Rejected, Withdrawn |
| Accepted | Ratified by the deciders; binding for designs in scope | Deprecated, Superseded |
| Rejected | Considered and turned down; kept so it is not reopened without new facts | None (raise a new decision) |
| Withdrawn | Dropped before a decision because the question no longer applies | None |
| Deprecated | No longer recommended for new work but still in place | Superseded |
| Superseded | Replaced by a named later decision | None |

```mermaid
stateDiagram-v2
  [*] --> Proposed
  Proposed --> Accepted: deciders ratify
  Proposed --> Rejected: deciders turn down
  Proposed --> Withdrawn: question no longer applies
  Accepted --> Deprecated: no longer for new work
  Accepted --> Superseded: replaced by later decision
  Deprecated --> Superseded: replaced by later decision
  Rejected --> [*]
  Withdrawn --> [*]
  Superseded --> [*]
```

### 2.3 Categories and levels

| Category code | Covers |
|---|---|
| STR | Structure: decomposition, boundaries, patterns |
| INT | Integration: styles, protocols, contracts, brokers |
| DAT | Data: stores, ownership, consistency, retention |
| TEC | Technology: languages, frameworks, products, services |
| INF | Infrastructure and hosting: regions, platforms, network |
| SEC | Security and identity |
| RES | Resilience, availability and recovery |
| OPS | Operations, observability, deployment |
| SRC | Sourcing: build, buy, reuse, vendor |

Levels: **E** enterprise (affects other solutions; ratified by the
architecture review board), **S** solution (affects several components of
this solution; ratified by the design authority), **C** component
(affects one component; logged here only when other teams depend on it).

### 2.4 Significance test

Write a full decision record when any of these apply; otherwise a log row
with a one-line rationale is enough:

- reversing it later would cost more than [N person-weeks or amount];
- it changes how two or more teams work or integrate;
- it is the main tactic for a Must NFR;
- it introduces a technology not on the approved list;
- it deviates from an enterprise principle or standard (also raise a waiver);
- it has a security, privacy, regulatory or contractual consequence;
- it commits spend or a vendor relationship above [amount].

## 3. Decision rights and roles

<!-- Guidance: Make clear who proposes, who is consulted, who decides and who is told, per level. Pitfall: decisions ratified by whoever happened to be in the meeting, which leads to reopening. -->

| Activity | Solution architect | Component tech lead | Design authority | Architecture review board | Security architect | Product owner | Operations |
|---|---|---|---|---|---|---|---|
| Raise a decision | R | R | C | I | R | C | R |
| Analyse options and write the record | A | R | C | I | C | C | C |
| Decide level C | C | A | I | I | C | I | I |
| Decide level S | R | C | A | I | C | C | C |
| Decide level E | R | I | C | A | C | I | C |
| Approve a waiver, level E (enterprise principle or standard) | R | I | C | A | C | I | I |
| Approve a waiver, level S or C (solution or component standard) | R | C | A | I | C | I | I |
| Communicate and update designs | A | R | I | I | I | I | I |

R responsible, A accountable, C consulted, I informed. *Example:* one
accountable role per row; adjust the columns to your organisation.

## 4. Decision log

<!-- Guidance: One row per decision, sorted by ID. Keep the title and drivers short; the record holds the detail. Every Accepted row needs a review date. -->

| ID | Title | Cat. | Level | Status | Date | Owner | Deciders | Drivers | Affects | Record | Review by |
|---|---|---|---|---|---|---|---|---|---|---|---|
| ADR-001 *(Example)* | Run a self-managed message broker on virtual machines | INT | S | Superseded by ADR-007 | YYYY-MM-DD | @integration-lead | Design authority | NFR-RE-001, cost | IF-003 | [link] | Not applicable |
| ADR-002 *(Example)* | Use a managed relational database for order data | DAT | S | Accepted | YYYY-MM-DD | @solution-architect | Design authority | NFR-RE-002, NFR-FS-001 | CMP-002 | [link] | YYYY-MM-DD |
| ADR-003 *(Example)* | Publish order events with the transactional outbox pattern | INT | S | Accepted | YYYY-MM-DD | @orders-lead | Design authority | NFR-RE-004 | CMP-002, IF-003 | [link] | YYYY-MM-DD |
| ADR-004 *(Example)* | Create payment intents synchronously with a 350 ms p95 budget and 450 ms timeout | INT | S | Accepted | YYYY-MM-DD | @payments-lead | Design authority | NFR-PE-001 | CMP-002, CMP-003, IF-002, IF-005; waiver WVR-001 | [link] | YYYY-MM-DD |
| ADR-005 *(Example)* | Authenticate service-to-service calls with federated workload identities | SEC | E | Accepted | YYYY-MM-DD | @security-architect | Architecture review board | NFR-SE-004, zero trust principle | All components | [link] | YYYY-MM-DD |
| ADR-006 *(Example)* | Offer a GraphQL public API for partners | INT | S | Rejected | YYYY-MM-DD | @solution-architect | Design authority | NFR-CO-002 | IF-001 | [link] | Not applicable |
| ADR-007 *(Example)* | Use the provider's managed message broker service | INT | S | Accepted | YYYY-MM-DD | @integration-lead | Design authority | NFR-RE-001, NFR-OP-004 | IF-003 | [link] | YYYY-MM-DD |
| ADR-008 *(Example)* | Deploy in two regions, active and warm standby | RES | S | Accepted | YYYY-MM-DD | @solution-architect | Design authority | NFR-RE-002, NFR-CT-001 | Platform, database | [link] | YYYY-MM-DD |
| ADR-009 *(Example)* | Select the search technology for order search | TEC | S | Proposed | Not applicable | @orders-lead | Design authority | NFR-PE-003 | CMP-002 | [draft link] | Need by YYYY-MM-DD |
| ADR-010 *(Example)* | Buy or build the feature flag service | SRC | E | Proposed | Not applicable | @platform-lead | Architecture review board | NFR-OP-002 | All components | [draft link] | Need by YYYY-MM-DD |
| [ADR-NNN] | [Title] | [Cat.] | [E / S / C] | [Status] | YYYY-MM-DD | [@owner] | [Forum] | [IDs] | [Elements] | [Link] | YYYY-MM-DD |

## 5. Decision summaries

<!-- Guidance: Give each Accepted decision a one-sentence summary so that readers can understand the log without opening every record. The Y-statement shape works well: context, concern, choice, rejected options, benefit, accepted downside. -->

| ID | Summary |
|---|---|
| ADR-002 *(Example)* | In the context of order capture, facing strict recovery objectives and the need for transactional consistency, we chose a managed relational database over a document store and a self-managed cluster, to get point-in-time recovery and cross-region replicas with low operating effort, accepting vendor coupling and a per-hour cost. |
| ADR-003 *(Example)* | In the context of event publication from the order service, facing the risk of lost or phantom events when database and broker writes diverge, we chose the transactional outbox over dual writes and change data capture, to guarantee that every committed change is published, accepting at-least-once delivery and the need for idempotent consumers. |
| ADR-004 *(Example)* | In the context of checkout, facing a customer who waits for a payment redirect, we chose a synchronous intent call with a 350 ms p95 budget and a 450 ms timeout at the measured p99, with no inline retry, over an asynchronous request and poll, to keep the journey simple while the timeout path still fits the 800 ms minimum (50 + 300 + 450 ms), accepting about 1 % client retries and a direct runtime dependency on the provider (covered by WVR-001). |
| ADR-007 *(Example)* | In the context of order events, facing the operating load and patching gaps of the self-managed broker, we chose the managed broker service over keeping ADR-001, to meet availability with less effort, accepting a migration of topics and consumer configuration. |
| ADR-008 *(Example)* | In the context of regional outages, facing an RTO of 1 hour and a cost ceiling, we chose active and warm standby over active-active, to meet recovery objectives at about [x] % of the active-active cost, accepting a manual failover decision. |
| [ADR-NNN] | [Summary] |

## 6. Superseded and deprecated decisions

<!-- Guidance: Show what replaced what, why, and whether the migration away from the old decision is finished. A superseded decision whose migration is incomplete is still running in production. -->

| ID | Status | Replaced by | Reason | Migration state | Completion date |
|---|---|---|---|---|---|
| ADR-001 *(Example)* | Superseded | ADR-007 | Patching effort and two unplanned outages in test | Topics moved; consumers in progress (3 of 4) | YYYY-MM-DD |
| [ADR-NNN] | [Status] | [ADR-NNN] | [Reason] | [State] | YYYY-MM-DD |

## 7. Pending decisions

<!-- Guidance: List every decision that must be made, the latest date it can be made without blocking work (the last responsible moment), what it blocks and what happens if it is late. Escalate any row whose need-by date is inside the next review period and that has no recommendation yet. -->

| ID | Question | Options under study | Need by | Blocks | Default if late | Owner | State |
|---|---|---|---|---|---|---|---|
| ADR-009 *(Example)* | Which search technology serves order search? | Database full-text, managed search service, embedded library | YYYY-MM-DD | LLD-002 section 6, sprint [n] | Database full-text for release 1 | @orders-lead | Spike running |
| ADR-010 *(Example)* | Buy or build feature flags? | SaaS product, open-source self-hosted, in-house | YYYY-MM-DD | Rollout plan in HLD section 13 | Configuration flags without targeting | @platform-lead | Build vs Buy Analysis (`architecture/build-vs-buy-analysis`) in progress |
| [ADR-NNN] | [Question] | [Options] | YYYY-MM-DD | [What waits] | [Fallback] | [@owner] | [State] |

## 8. Rejected and withdrawn proposals

<!-- Guidance: Keep the reason for rejection in one line, and the condition under which it could be reconsidered. This stops the same proposal returning every quarter. -->

| ID | Proposal | Status | Reason | Reconsider if |
|---|---|---|---|---|
| ADR-006 *(Example)* | GraphQL public API for partners | Rejected | Partners asked for REST; no team has GraphQL operating experience; caching and rate limiting harder at the gateway | Three or more partners request flexible queries |
| [ADR-NNN] | [Proposal] | [Rejected / Withdrawn] | [Reason] | [Condition] |

## 9. Waivers and dispensations

<!-- Guidance: A waiver records an approved deviation from an enterprise principle, standard or reference architecture, with compensating measures and an expiry. Pitfall: permanent waivers, which are new standards nobody approved. -->

| ID | Deviates from | Decision | Justification | Compensating measures | Approved by | Expires | State |
|---|---|---|---|---|---|---|---|
| WVR-001 *(Example)* | Integration standard: calls to external providers go through a queue | ADR-004 | Customer waits for the redirect; a queue adds latency beyond NFR-PE-001 | Circuit breaker, timeout, pending-order expiry, provider SLA monitoring | Architecture review board | YYYY-MM-DD | Active |
| WVR-002 *(Example)* | Standard logging library | Component CMP-004 uses the vendor adapter's built-in logger | Vendor adapter cannot load the standard library | Log format mapped to the standard schema at the collector | Design authority | YYYY-MM-DD | Active, review at vendor upgrade |
| [WVR-NNN] | [Principle or standard] | [ADR ID] | [Why] | [Measures] | [Forum] | YYYY-MM-DD | [Active / Expired / Closed] |

Enterprise compliance checks: Architecture Compliance Assessment
(`architecture/architecture-compliance-assessment`).

## 10. Decision dependencies

<!-- Guidance: Show which decisions constrain others, so that reopening one decision reveals what else must be revisited. Keep the diagram to the decisions that have dependants. -->

Arrows point from a decision to the decisions that depend on it.

```mermaid
flowchart LR
  A002["ADR-002 Managed relational DB"] --> A003["ADR-003 Transactional outbox"]
  A007["ADR-007 Managed broker"] --> A003
  A001["ADR-001 Self-managed broker (superseded)"] -.replaced by.-> A007
  A002 --> A008["ADR-008 Active and warm standby"]
  A005["ADR-005 Workload identity"] --> A007
  A003 --> A009["ADR-009 Search technology (pending)"]
```

| Decision | Depends on | If the upstream decision changes |
|---|---|---|
| ADR-003 *(Example)* | ADR-002, ADR-007 | Outbox relay must be redesigned for a new store or broker |
| ADR-008 *(Example)* | ADR-002 | Cross-region replication approach changes |
| ADR-009 *(Example)* | ADR-003 | Search index fed from order events; a different event path changes indexing |
| [ADR-NNN] | [ADR IDs] | [Consequence] |

## 11. Traceability

<!-- Guidance: Link each decision to the drivers that justify it and the documents that implement it. An Accepted decision with no driver is a preference; one with no implementing document may not have been applied. -->

| Decision | Drivers | Principles | Implemented in | Verified by |
|---|---|---|---|---|
| ADR-003 *(Example)* | NFR-RE-004 | Single writer per data entity | HLD section 7, LLD-002 sections 6 and 10 | IT-ORD-002 |
| ADR-004 *(Example)* | NFR-PE-001 | Integration standard on queued provider calls (waived, WVR-001) | HLD sections 6 and 9, LLD-002 sections 5, 11 and 14, LLD-003 | PT-01, PT-ORD-01 |
| ADR-008 *(Example)* | NFR-RE-002, NFR-CT-001 | Design for failure | HLD sections 8 and 11 | DR-01 |
| [ADR-NNN] | [NFR or risk IDs] | [Principle] | [Documents] | [Test or review] |

Drivers come from the NFR Catalogue (`requirements/nfr-catalogue`) and
Architecture Principles (`architecture/architecture-principles`).

## 12. Review cadence and health metrics

<!-- Guidance: Review the log on a schedule and measure whether decisions are being made on time and kept current. Report the metrics to the design authority. -->

| Review | When | Who | Checks |
|---|---|---|---|
| Log review *(Example)* | Every two weeks during design, monthly in delivery | Log owner and component leads | New decisions logged, pending need-by dates, status changes |
| Design authority *(Example)* | Monthly | Design authority | Ratify Proposed level S decisions with records; approve level S and C waivers; refer level E waivers to the architecture review board |
| Decision revalidation *(Example)* | Each Accepted decision on its review date, at least yearly | Decision owner | Drivers still valid, assumptions still true, cost as expected |
| Release gate *(Example)* | Before each major release | Solution architect | No pending decision blocks the release; waivers in date |
| [Review] | [When] | [Who] | [Checks] |

| Metric | Definition | Target *(Example)* |
|---|---|---|
| Overdue pending decisions | Proposed rows past their need-by date | 0 |
| Decision lead time | Median days from Proposed to Accepted or Rejected | Under 15 working days |
| Record coverage | Accepted decisions that pass the significance test and have a full record | 100 % |
| Stale decisions | Accepted rows past their review date | 0 |
| Expiring waivers | Active waivers expiring within 30 days without a renewal request | 0 |
| Reopened decisions | Decisions reopened without new facts in the last quarter | 0 |

## 13. Decision process

<!-- Guidance: Describe the steps from raising a question to communicating the outcome, so that every decision follows the same path. Keep it light enough that teams use it. -->

1. **Raise.** Anyone adds a Proposed row with a question, owner and
   need-by date (section 7).
2. **Frame.** The owner lists drivers (NFR IDs, principles, risks,
   constraints) and at least two realistic options, including "do
   nothing" where it is viable. For sourcing questions, use Build vs Buy
   Analysis (`architecture/build-vs-buy-analysis`) or Solution Options
   Analysis (`architecture/solution-options-analysis`).
3. **Analyse.** The owner writes the record in the chosen format and
   consults the roles in section 3. For decisions that trade qualities
   against each other, use scenarios from Quality Attributes
   (`requirements/quality-attributes`) or an ATAM Evaluation
   (`architecture/atam-evaluation`).
4. **Decide.** The accountable forum ratifies, rejects or asks for more
   analysis, and the row status changes on the same day.
5. **Communicate.** The owner updates the HLD, SAD and affected LLDs,
   informs dependent teams and, if a principle is not followed, raises a
   waiver (section 9).
6. **Revisit.** On the review date or when a driver changes, the owner
   confirms the decision or raises a new decision that supersedes it.

Architecture changes that need board approval: Architecture Change
Request (`architecture/architecture-change-request`); review submissions:
Architecture Review Request (`architecture/architecture-review-request`).

## 14. Glossary and references

<!-- Guidance: Define the terms used and list the sources, with versions and the date you checked them. -->

### 14.1 Glossary

| Term | Meaning |
|---|---|
| Architecture decision | A choice about structure, technology or quality tactics that is costly to change and affects the system as a whole or several parts |
| Decision record (ADR) | Short document that captures one decision with its context, options, outcome and consequences |
| Decision log | The collection of decisions for a scope, with their status |
| Supersede | Replace an accepted decision with a later one that is now binding |
| Waiver | Approved, time-limited deviation from a principle or standard |
| Last responsible moment | The latest date a decision can be made before a valuable option is lost or delivery is blocked |
| Y-statement | One-sentence decision summary naming context, concern, choice, rejected options, benefit and accepted downside |
| [Term] | [Meaning] |

### 14.2 References

| ID | Reference | Version or date | Use |
|---|---|---|---|
| REF-01 | Michael Nygard, "Documenting Architecture Decisions", Cognitect blog | 15 November 2011 | ADR practice and statuses |
| REF-02 | Architectural Decision Records, adr.github.io | Checked 2026-10-23 | Decision log concept, templates overview |
| REF-03 | MADR, Markdown Architectural Decision Records, adr.github.io/madr | 4.0.0, 17 September 2024 | Record format and statuses |
| REF-04 | U. Zdun, R. Capilla, H. Tran, O. Zimmermann, "Sustainable Architectural Design Decisions", IEEE Software 30(6) | 2013 | Y-statement summary format |
| REF-05 | ISO/IEC/IEEE 42010:2022, Software, systems and enterprise: Architecture description | Edition 2, November 2022 | Decisions and rationale within an architecture description |
| REF-06 | ADR (Full) (`architecture/adr-full`) and MADR (`dev/madr`) | This collection | Record templates |

## Standard and licence note

Based on the architecture decision record practice described by Michael
Nygard (2011) and collected at adr.github.io, with record statuses
compatible with MADR 4.0.0 (MIT OR CC0-1.0) and the Y-statement summary
format from Zdun et al. (IEEE Software, 2013). Structure aligned with the
treatment of architecture decisions and rationale in ISO/IEC/IEEE
42010:2022; only concept names are used and no text, definitions or
tables are reproduced from the standard. This template is original text
written for this collection. Check the current versions at adr.github.io
and iso.org before use. Template licence: MIT.