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.

Document control

Approvals

Revision history

Contents

1. Purpose and scope
2. Conventions
3. Decision rights and roles
4. Decision log
5. Decision summaries
6. Superseded and deprecated decisions
7. Pending decisions
8. Rejected and withdrawn proposals
9. Waivers and dispensations
10. Decision dependencies
11. Traceability
12. Review cadence and health metrics
13. Decision process
14. Glossary and references

1. Purpose and scope

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

2. Conventions

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

2.3 Categories and levels

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

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

4. Decision log

5. Decision summaries

6. Superseded and deprecated decisions

7. Pending decisions

8. Rejected and withdrawn proposals

9. Waivers and dispensations

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

10. Decision dependencies

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

11. Traceability

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

12. Review cadence and health metrics

13. Decision process

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

14.1 Glossary

14.2 References

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.