TOGAF ADR Template — Mapping Decision Records to Phase H and the Architecture Repository

Why TOGAF doesn't have a native ADR format

TOGAF's Architecture Development Method (ADM) is a phased framework — eight phases (Preliminary plus A through H) that walk an enterprise through baseline, target, gap analysis, migration planning, governance, and change management. Each phase produces a defined set of deliverables: Architecture Vision (Phase A), Business Architecture (Phase B), Information Systems Architecture (Phase C), Technology Architecture (Phase D), Opportunities and Solutions (Phase E), Migration Planning (Phase F), Implementation Governance (Phase G), Architecture Change Management (Phase H).

The deliverables are heavyweight by design — Strategic Architectures, Segment Architectures, Capability Architectures, Architecture Requirements Specifications, Architecture Definition Documents, Architecture Roadmaps. They describe target states, not the trade-off reasoning that produced them. The ADM assumes those decisions happen inside Architecture Board reviews and live as governance log entries, not as standalone documents.

That model worked when EA teams produced architectures on multi-year cycles and could run every decision through a formal governance review. It breaks at the rate modern teams actually make decisions. A typical platform team in a TOGAF-compliant enterprise might make 10–15 durable architectural choices per quarter (caching strategy, retry semantics, service boundaries, data partitioning) — a rate that overwhelms any practical Architecture Board cadence. The ADR practice fills the gap: lightweight, decentralized, defensible. But the practice has to land somewhere in TOGAF's deliverable hierarchy or it becomes shadow documentation that the auditors flag.

The field-to-deliverable mapping

Seven fields connect a Nygard-shaped ADR to TOGAF's deliverable set. Add them to whatever body template you've already standardized on (the Nygard template or MADR are the common choices); the mapping is a discipline applied on top, not a replacement.

Three of these — Stakeholder Mapping, Requirements Traceability, Capability Impact — are the load-bearing audit fields. They're what an enterprise architect can point to during a TOGAF audit to demonstrate the decision was made with proper visibility, traceability, and impact assessment. The other four are routing metadata that determines where the ADR lives and who reviews it.

The TOGAF ADR template — copy-paste version

The template below extends Nygard's original five-section format with the seven TOGAF fields as a YAML frontmatter block, plus an Impact Assessment section that's standard in TOGAF Phase H change requests. Copy it as doc/decisions/0001-template-togaf-adr.md in your Architecture Repository (whatever storage layer you've picked — see the storage format comparison).

---
status: Proposed              # Proposed | Accepted | Superseded | Deprecated | Rejected
id: 0042
title: Adopt CQRS for Customer Master Data reads
date: 2026-05-01
ea_domain: Data               # Business | Data | Application | Technology
adm_phase: H                  # A | B | C | D | E | F | G | H
abb: Customer-Master-Data     # Architecture Building Block reference
stakeholder_mapping:
  - { name: "Data Architecture Lead", role: "decision-maker" }
  - { name: "Customer Domain Product Manager", role: "consulted" }
  - { name: "Operations Lead", role: "informed" }
  - { name: "Security Architect", role: "consulted" }
requirements_traceability:
  - { id: "ARS-3.2.1", text: "Master data reads p99 < 50ms" }
  - { id: "ARS-3.2.4", text: "Read scaling independent of write throughput" }
capability_impact:
  - { capability: "Customer Onboarding", impact: "indirect — read latency" }
  - { capability: "Customer 360 Reporting", impact: "direct — read model becomes source" }
repository_placement: Architecture Landscape / Customer Master Data
governance_review_id: AB-2026-04-12-CQRS    # Architecture Board minute reference, if applicable
---

# 0042. Adopt CQRS for Customer Master Data reads

## Status

Proposed (per Phase H minor change request CR-2026-0317; targeted for Architecture
Board review on 2026-05-15).

## Context

The Customer Master Data Architecture Building Block currently serves both reads
and writes from a single normalized Postgres schema. Read traffic has grown 4x in
the last 18 months while write traffic is flat. p99 read latency now exceeds the
ARS-3.2.1 budget (50ms) under peak load, and read scaling drags write performance
because they share the same connection pool.

The Capability Map (Customer Onboarding and Customer 360 Reporting) shows
read-heavy capabilities that are coupled to write throughput in a way that the
target architecture for the Data Domain (per Phase C deliverable, dated 2025-11)
explicitly identifies as a known gap.

## Decision

Adopt CQRS (Command Query Responsibility Segregation) for the Customer Master
Data ABB. Writes continue against the normalized Postgres schema. Reads move to
a denormalized read store (initial choice: PostgreSQL replica with a
Debezium-driven projection pipeline, evaluated alternatives below).

## Alternatives considered

1. **Vertical scaling of the existing schema.** Rejected — projected to defer
   the latency problem 12-18 months at significant cost; doesn't address read/write
   coupling.
2. **Read replicas without CQRS denormalization.** Rejected — addresses scaling but
   not the latency budget under join-heavy reads (ARS-3.2.1).
3. **Full event-sourced rewrite.** Rejected — out of scope for this change; would
   require a Phase A re-baseline, not a Phase H minor change.
4. **CQRS with the read store on a managed search service (Elasticsearch).**
   Considered; rejected for this iteration because the operational expertise gap
   in the Data team is wider for ES than for managed Postgres replicas. Revisit
   after the team has 12 months of experience operating the simpler design.

## Consequences

### Positive
- Read latency comes back under the ARS-3.2.1 budget at projected 3-year traffic.
- Read and write scaling decouple, satisfying ARS-3.2.4.
- The denormalization layer is a natural place to land the Customer 360 reporting
  read model the BI team has been requesting.

### Negative
- Operational complexity increases — two stores instead of one, plus the
  Debezium projection pipeline. Estimate +1.5 SRE FTE-equivalent at steady state.
- Read-after-write consistency window: 200-500ms typical, 2s worst-case during
  projection backlog. Customer Onboarding capability owner (consulted) confirmed
  this is acceptable for the read paths in scope.
- The Architecture Repository now needs to track two views of Customer Master Data
  (the write model and the read model). Update the Customer Master Data ABB
  documentation to describe both.

## Impact assessment (Phase H deliverable)

| Architecture | Impact | Action required |
|---|---|---|
| Business Architecture | Low — capability boundaries unchanged | None |
| Data Architecture | High — new ABB sub-component (read store) | Update Data ABB inventory; new schema documentation |
| Application Architecture | Medium — applications routing reads to a new endpoint | Service contract updates for 4 consumer services |
| Technology Architecture | Low — no new platform components | None |

## Compliance

This change is consistent with the Phase D Technology Architecture decision (TR-2024-0089,
"prefer managed Postgres replicas over self-managed alternatives") and with the
Data Domain target architecture's explicit identification of read/write coupling as
a baseline gap.

## Notes

(Reserved for future context shifts that don't reverse the decision; see the
Notes-section convention in how to update an ADR.)

The frontmatter is the TOGAF mapping; the body is a standard Nygard ADR with the Impact Assessment section added (which is required for Phase H change requests). The governance_review_id field is optional — only populate it when the ADR went through a formal Architecture Board review; for routine Phase H minor changes, leave it absent.

Repository placement — three options, pick one per ADR

Architecture Landscape (the default)

Most ADRs belong here. The Architecture Landscape is TOGAF's view of the as-is and to-be architectures across the enterprise; ADRs about specific Architecture Building Blocks live alongside the architecture documents that describe those ABBs. A typical layout:

architecture-repository/
├── architecture-landscape/
│   ├── strategic/
│   │   └── enterprise-vision-2026.md
│   ├── segment/
│   │   ├── customer-domain/
│   │   │   ├── architecture-definition.md
│   │   │   └── decisions/
│   │   │       ├── 0001-customer-identity-consolidation.md
│   │   │       ├── 0042-cqrs-for-master-data-reads.md
│   │   │       └── README.md   # auto-built index
│   │   └── product-domain/
│   │       └── ...
│   └── capability/
│       └── ...
├── reference-library/
│   └── decisions/
│       ├── 0103-default-retry-policy.md
│       └── 0104-default-tracing-baseline.md
└── governance-log/
    └── decisions/
        └── 0007-architecture-board-2026-q1.md

Per-ABB decision directories keep the cardinality manageable — a 200-ADR enterprise architecture practice has 200 files across ~15 ABB directories rather than 200 in a single flat directory. The naming follows the numbering scheme (4-digit zero-padded) but numbers are scoped per directory; the full reference is customer-domain/decisions/0042.

Reference Library

For ADRs that codify a reusable pattern or constraint that applies across multiple ABBs. Examples: "default retry policy for inter-service calls," "default tracing baseline," "default approach to PII tokenization." These are the ADRs that show up as referenced standards inside other ADRs.

The bar for Reference Library placement is high — a Reference Library ADR creates an obligation for every team to comply, so promotion to the Reference Library is itself often an Architecture Board decision (which produces an ADR in the Governance Log too). Most teams under-use the Reference Library; default to Architecture Landscape and only promote when a pattern has demonstrably emerged.

Governance Log

For ADRs that ARE the output of a formal Architecture Board review. The governance_review_id frontmatter field links them to the corresponding Architecture Board minutes. These are usually high-impact decisions — a major change in Phase H, a Phase A re-baseline trigger, or a deviation from a Reference Library standard. The Governance Log is the slowest-changing slice of the repository and the one auditors look at first.

Stakeholder mapping in practice

The stakeholder_mapping frontmatter array is the field most TOGAF audits surface in interviews. The rule of thumb: at least one decision-maker, at least one consulted role per affected EA Domain, and at least one informed role from operations. For the CQRS example above:

• Decision-maker — the Data Architecture Lead, because the decision is in the Data Domain. For cross-domain decisions, you'd have multiple decision-makers (one per domain) or a single decision-maker designated by the Architecture Board.
• Consulted — the Customer Domain Product Manager (because the affected ABB is in the Customer Segment), the Security Architect (because data store changes touch security review). For larger decisions, add Application Architecture Lead, Technology Architecture Lead, and the relevant capability owner.
• Informed — Operations Lead (because the change adds operational complexity). For decisions that affect customer-visible behavior, add the Customer Experience Lead.

Names beat titles when possible — auditors prefer "Sara Lin" to "Data Architecture Lead" because they can verify Sara was actually consulted. Where names aren't appropriate (long-term documents, personnel changes), use roles + a current-occupant pointer to a separate roster file. The trade-off is documented in adr-status-template under the decision-by field discussion.

Four common mistakes

1. Treating every ADR as a Phase H minor change

Not every ADR needs a Phase H change request. Phase H is for changes from the baseline architecture. ADRs that codify decisions within the baseline — e.g. "we picked PostgreSQL over MySQL when we built this segment originally" — are framing decisions, not change records. Routing them through Phase H creates governance overhead that tanks ADR adoption. Use the adm_phase field correctly: A for vision-level framing, C for Information Systems framing, D for Technology framing, H only for changes from baseline.

2. Putting every ADR in the Governance Log

Inverted version of the same mistake. The Governance Log is for Architecture-Board-reviewed decisions. Routing every ADR through the Architecture Board overwhelms the Board's cadence (typical EA practice can produce 10–15 ADRs per quarter; an Architecture Board meets monthly with maybe two slots per agenda). The right placement for routine ADRs is Architecture Landscape; the Governance Log is reserved for the few decisions that genuinely warrant Board review (cross-domain conflicts, deviations from Reference Library standards, Phase A re-baseline triggers).

3. Skipping requirements traceability "because it's obvious"

The requirements_traceability field is the one auditors test by sampling. "We adopted CQRS to improve read performance" without an ARS reference doesn't survive a TOGAF audit because there's no way to verify the requirement was actually documented before the decision. The fix is mechanical — every Phase H change request should reference at least one Architecture Requirements Specification entry; if no ARS entry covers it, that's a signal the requirement should be added to the ARS first.

4. Numbering ADRs across the whole enterprise

Tempting and wrong. A flat enterprise-wide ADR numbering scheme creates merge collisions across segment teams and makes per-segment archive operations awkward. The right pattern is per-directory numbering scoped to the EA Domain or Segment: customer-domain/decisions/0042-..., product-domain/decisions/0017-.... The full reference inside other ADRs uses the path-prefixed form. The merge-base allocator from the numbering scheme guide works per-directory and avoids collisions across parallel branches within each segment.

How TOGAF ADRs differ from arc42 ADRs

Both frameworks come from the European EA tradition. The difference is scope and ceremony.

Many enterprises run both — arc42 ADRs at the system-architecture level for individual products, TOGAF ADRs at the segment-architecture level when a decision spans multiple products. The arc42 ADR can reference a TOGAF ADR ("this decision is constrained by Customer Domain ADR 0042 in the Architecture Landscape") and vice versa. The cross-references are what makes the audit trail navigable.

For a single-product team, the TOGAF mapping is overhead — pick the arc42 template instead. For a multi-product enterprise with formal governance, the TOGAF mapping is what makes the practice defensible during audits. Most teams should default to arc42 or Nygard until they have either (a) a TOGAF program in place, (b) regulated-industry compliance requirements that demand the requirements traceability, or (c) cross-segment decisions that are getting lost.

Three failure modes without TOGAF mapping

1. The audit gap. Auditor asks "show me the decision to adopt CQRS for Customer Master Data," and the enterprise architect produces an ADR. Auditor asks "show me which Architecture Requirement that satisfies, and who was consulted," and the answer is "it's in the document somewhere" — which means it's nowhere. The TOGAF mapping (specifically requirements_traceability and stakeholder_mapping) makes the answer mechanical.
2. The cross-segment collision. Two segment teams independently make conflicting decisions (one team adopts Kafka, another team adopts SQS for the same kind of pattern). Without the capability_impact field, the conflict isn't visible until both decisions ship. With the field, a CI script can find the collision before merge — every ADR's capability impact is checked against the Capability Map, and conflicts surface as PR review comments.
3. The Reference Library that never materializes. Without explicit repository_placement, every ADR ends up in Architecture Landscape, even patterns that should be promoted to the Reference Library. Six months in, the Reference Library is empty and every team is reinventing the same patterns. The placement field forces the question at write-time.

How WhyChose fits in

Most architecture decisions in TOGAF-compliant enterprises are made in chat conversations between architects, not in formal review meetings. The Phase H change request that ships an ADR is the documented output; the actual reasoning happens days or weeks earlier, in a long ChatGPT or Claude conversation about latency budgets, retry semantics, or data consistency models. The WhyChose extractor reads those chat exports and surfaces decision-shaped exchanges with the trade-offs considered at the time — including the alternatives sections that auditors test by asking "what else did you consider?" The extractor's output is YAML-frontmattered Markdown; populate the seven TOGAF fields manually (the LLM doesn't know your Capability Map or your ARS), drop into architecture-repository/architecture-landscape/<segment>/decisions/, and run the merge-base allocator to assign a number. The decision archaeology question — "what conversation produced this ADR?" — is answerable because the extracted record carries the original chat snippet as a backlink. For a TOGAF program at scale, this is the difference between "the audit trail is the ADR" and "the audit trail is the ADR plus the reasoning that produced it."

Get early access

Related questions

Further reading

• The Nygard ADR template — the body shape this template extends with the TOGAF frontmatter.
• MADR template — the alternative body shape; the seven TOGAF fields work identically with MADR.
• arc42 ADR template — the lighter European EA framework; right for single-product teams that don't need the TOGAF mapping.
• Architecture decision record template — the broader head term; covers the three template flavors (Nygard / MADR / arc42) with a decision tree for picking.
• ADR storage format comparison — Markdown vs Notion vs Confluence vs SharePoint vs AsciiDoc as Architecture Repository storage.
• ADR numbering scheme — the per-directory numbering pattern; works inside per-segment Architecture Landscape directories without cross-team collision.
• ADR status template — the Status field's format and the five-state lifecycle; integrates with the TOGAF Phase H change request states.
• How to update an ADR — the supersession protocol; works identically in TOGAF Architecture Repository placements.
• The ADR GitHub Action — CI checks for structure and supersession integrity; extend with TOGAF-specific lint rules (every ADR has at least one ARS reference, at least one stakeholder).
• How to document architecture decisions — the cultural pairing; TOGAF programs face the same "ADRs go stale" failure mode and the same mitigations apply.
• ADR vs Design Decision Record — disambiguation; in TOGAF the line is between Phase H minor changes (ADR territory) and Solution Building Block specifications (DDR territory).
• The open-source extractor — pre-fills the body of TOGAF-shaped ADRs from chat exports; the seven mapping fields are populated manually because the LLM doesn't know your Capability Map.