> tpl_arc_002
Architecture Decision Record (ADR) Pack
Production-grade architectural decision governance framework based on MADR 3.0 and ISO 42010 with state machine lifecycle, weighted options matrix, and trade-off registers.
Standardized MADR 3.0 template and worked example evaluating Outbox Saga vs 2PC for distributed banking transactions. Includes decision drivers, weighted evaluation scoring, consequences, and rollback protocols.
Important Tech Document Template & Operational Notice
TinyCTO.tv Tech Document Template Notice: This template is a general educational and operational starting point. It is not legal, tax, accounting, investment, procurement, regulatory, security or certification advice. Requirements vary by jurisdiction, organization, contract and risk. Review and adapt it with qualified professionals before relying on it.
Problem Solved
Prevents tribal architectural drift, undocumented hacks, and unprincipled framework switching by establishing an immutable, versioned audit trail for significant engineering choices.
When to Use
- •Whenever deciding on non-trivial architectural patterns (microservices, event-driven, CQRS, sagas).
- •When introducing a new foundational infrastructure layer, database, or message broker.
- •When deprecating or replacing legacy distributed consensus protocols.
- •When establishing compliance and architectural traceability for external SOC 2 or PCI-DSS audits.
When NOT to Use
- •For trivial code-level refactors or routine library patch upgrades (use standard Git PR descriptions).
- •For UI styling choices, CSS framework tweaks, or non-architectural frontend cosmetics.
- •For temporary feature toggles that have no permanent structural impact.
7 Template Sections & Structural Outline
Formal decision title, state machine status, and ARB review participants.
The business and technical forces compelling this decision.
Quantifiable evaluation criteria ranking candidate architectures.
Comparative analysis of candidate options scored against drivers.
Formal decision statement and core technical invariants.
Concrete capabilities unlocked by this decision.
Operational costs, complexities, and technical debt incurred.
Completion Instructions
Independent Review Checklist
- Does the title state an active technical decision rather than a generic topic?
- Does the context present factual forces without prematurely forcing the solution?
- Were at least three distinct candidate architectures evaluated with weighted scoring?
- Are negative consequences and operational burdens acknowledged with mitigations?
- Is a rollback or dark-launch contingency plan explicitly documented?
ADR-042: Event-Driven Transactional Outbox Saga for Core Banking Ledger
Fictional Entity: ApexGlobal Banking Core v4.0
Replacing lock-heavy Two-Phase Commit (2PC) with an asynchronous Transactional Outbox Saga using Temporal and Debezium CDC under 10,000 TPS peak load.
- •P99 settlement latency dropped from 4,200ms to 142ms (96.6% reduction).
- •Eliminated catastrophic distributed lock cascades across availability zones.
- •Cryptographically verified outbox event stream provides automated audit compliance.
Frequently Asked Questions
When should an ADR be marked as SUPERSEDED instead of REJECTED?
An ADR is marked SUPERSEDED only after it was previously ACCEPTED and operated in production, but subsequent technological evolution or requirements made a newer decision necessary. REJECTED is used during initial review when a proposal is declined.
Where should ADRs be stored in the codebase?
ADRs should live alongside code in version control, typically in `docs/adr/` or `_PM/Agent-PM/Docs/ADRs/` as numbered Markdown files (e.g. `ADR-0042-outbox-saga.md`).
Download Tech Document Pack
Auth RequiredDownload all blank templates, worked scenarios, and verification manifests in a single verified archive.
Authoritative Sources
- Documenting Architecture Decisions (Michael Nygard)Cognitect • INDUSTRY PRACTICE
- Markdown Architectural Decision Records (MADR 3.0)ADR GitHub Community • OFFICIAL RECOMMENDATION