​

Architecture Decision Records (ADR)

​

What is an ADR?

• Context: Why this decision is needed
• Options: Alternatives considered (minimum 2-3 plus “Do Nothing”)
• Decision: Which option was chosen
• Consequences: Positive, negative, and neutral impacts
• Rationale: Why this option over alternatives

​

MADR v4.0 Format

​

Document Metadata

• ADR Number: Sequential (ADR-001, ADR-002, etc.)
• Status: Proposed / Accepted / Deprecated / Superseded
• Date: When decision was made
• Escalation Level: Team / Cross-team / Department / Cross-government
• Governance Forum: Architecture Review Board, TDA, etc.

​

Stakeholder RACI

• Deciders: Who has authority to approve (Accountable)
• Consulted: Subject matter experts (two-way communication)
• Informed: Stakeholders to keep updated (one-way communication)

​

Context and Problem Statement

• Problem description (2-3 sentences or story format)
• Why is this decision needed?
• Business context (link to BR-xxx requirements)
• Technical context (link to FR-xxx, NFR-xxx requirements)
• Regulatory context (GDPR, GDS Service Standard, Cyber Essentials)

​

Decision Drivers (Forces)

• Technical drivers: Performance, scalability, maintainability, security
• Business drivers: Cost, time to market, risk reduction
• Regulatory & compliance drivers: GDS Service Standard, TCoP, NCSC, UK GDPR
• Alignment to architecture principles: Which principles support/conflict

​

Considered Options

• Description: What is this option?
• Implementation approach: How would it be implemented?
• Wardley Evolution Stage: Genesis / Custom-Built / Product / Commodity
• Good (Pros): Benefits, requirements met, principles supported
• Bad (Cons): Drawbacks, requirements not met, risks
• Cost Analysis: CAPEX, OPEX, TCO (3-year)
• GDS Service Standard Impact: Impact on relevant points

​

Decision Outcome

• Chosen Option: Which option was selected
• Y-Statement (structured justification):

  In the context of [use case], facing [concern], we decided for [option], to achieve [quality/benefit], accepting [downside/trade-off].

• Justification: Why this option over alternatives?

​

Consequences

• Positive: Benefits, capabilities enabled, compliance achieved
• Negative: Accepted trade-offs, limitations, technical debt
• Neutral: Changes needed (training, infrastructure, process, vendors)
• Risks and Mitigations: Risk, likelihood, impact, mitigation, owner

​

When to Create an ADR

• Technology choices (databases, frameworks, cloud services, APIs)
• Integration patterns and protocols
• Security and compliance approaches
• Deployment and infrastructure decisions
• Data management and privacy decisions

• Minor implementation details (variable names, coding style)
• Temporary workarounds or fixes
• Decisions that don’t affect other teams or systems

​

UK Government Escalation Levels

​

Example: PostgreSQL for Data Persistence

​

Y-Statement

In the context of storing transactional payment data, facing the need for ACID compliance and complex queries, we decided for PostgreSQL on AWS RDS, to achieve data consistency and operational simplicity, accepting vendor lock-in to AWS.

​

Options Considered

1. PostgreSQL on AWS RDS (Product, 0.92)
   • ✅ ACID compliance
   • ✅ Mature ecosystem
   • ✅ AWS operational support
   • ❌ AWS vendor lock-in
   • CAPEX: £0, OPEX: £12K/year, TCO: £36K
2. MongoDB Atlas (Product, 0.88)
   • ✅ Flexible schema
   • ✅ Horizontal scaling
   • ❌ Eventual consistency
   • ❌ Complex transactions
   • CAPEX: £0, OPEX: £15K/year, TCO: £45K
3. Custom MySQL on EC2 (Custom, 0.55)
   • ✅ Full control
   • ✅ No vendor lock-in
   • ❌ Operational burden
   • ❌ No managed backups
   • CAPEX: £5K, OPEX: £20K/year, TCO: £65K
4. Do Nothing (Keep existing Oracle)
   • ✅ No migration cost
   • ❌ High licensing fees
   • ❌ Legacy technology
   • CAPEX: £0, OPEX: £50K/year, TCO: £150K

​

Decision: PostgreSQL on AWS RDS

• Meets all requirements (ACID, complex queries, scalability)
• Cloud-First principle (TCoP Point 5)
• Lowest TCO (£36K vs £45K, £65K, £150K)
• Operational simplicity (managed service)
• Accepted trade-off: AWS vendor lock-in (mitigated by PostgreSQL portability)

​

Usage

​

Basic Command

/arckit.adr Use PostgreSQL for data persistence

​

With Context

/arckit.adr API gateway selection for microservices
/arckit.adr Cloud provider choice for hosting
/arckit.adr Authentication strategy using OAuth 2.0

​

Interactive Configuration

1. Escalation level: Team / Cross-team / Department / Cross-government
2. Options count: 2, 3 (recommended), or 4+ options to evaluate

​

ADR Lifecycle

​

Status Transitions

• Proposed → Accepted (after approval)
• Accepted → Superseded (when replaced by new ADR)
• Accepted → Deprecated (when no longer recommended but not replaced)

​

ADR Numbering

• Sequential: ADR-001, ADR-002, ADR-003, etc.
• Never reuse numbers (even if ADR is superseded)
• Superseded ADRs remain in place with updated status

​

Review Schedule

• Initial review: 3-6 months after implementation
• Periodic review: Annually
• Trigger events: Version changes, cost changes, security incidents, regulatory changes

​

Integration with ArcKit Workflow

​

Before Creating ADR

/arckit.principles      # Establish decision framework
/arckit.requirements    # Define requirements ADR addresses
/arckit.research        # Research technology options
/arckit.wardley         # Understand evolution stage

​

During ADR Creation

/arckit.adr Create ADR for database selection

1. Read architecture principles
2. Read requirements
3. Read research findings (if available)
4. Read Wardley maps (if available)
5. Ask for escalation level and options count
6. Generate comprehensive ADR with all sections
7. Write to projects/{project-dir}/decisions/ARC-{PROJECT_ID}-ADR-{NUM}-v1.0.md

​

After ADR Creation

/arckit.diagram         # Update architecture diagrams
/arckit.hld-review      # Reflect decision in HLD
/arckit.traceability    # Update traceability matrix

​

Output File Format

projects/{project-number}-{project-name}/decisions/ARC-{PROJECT_ID}-ADR-{NUM}-v1.0.md

​

Best Practices

​

Minimum Options

​

Y-Statement

​

Traceability

• Requirements (BR-xxx, FR-xxx, NFR-xxx)
• Architecture principles
• Stakeholder goals
• Risk register (RISK-xxx)

​

Evidence-Based

• Research findings
• Benchmarks
• Proof of Concepts (PoCs)
• Vendor proposals

​

Wardley Evolution

• Genesis/Custom: Consider building if strategic differentiator
• Product: Buy from market unless very specific needs
• Commodity: Always use utility/cloud services

​

Cost Analysis

​

Consequences

​

Validation

• Design review requirements
• Code review checklist
• Testing strategy (unit, integration, performance, security)
• Monitoring and observability

​

Common Decision Titles

• “Use PostgreSQL for Transactional Data Persistence”
• “Adopt API Gateway Pattern for Service Integration”
• “Deploy on Azure Government Cloud”
• “Implement OAuth 2.0 with Azure AD for Authentication”
• “Use Event-Driven Architecture for Real-Time Processing”
• “Choose React with TypeScript for Frontend Development”
• “Implement Microservices over Monolithic Architecture”
• “Use Terraform for Infrastructure as Code”
• “Adopt Kubernetes for Container Orchestration”
• “Implement CQRS Pattern for Read/Write Separation”

​

Related Commands

• /arckit.principles - Establish decision framework
• /arckit.requirements - Define requirements
• /arckit.research - Research technology options
• /arckit.wardley - Understand evolution stage
• /arckit.diagram - Update architecture diagrams
• /arckit.hld-review - Reflect decision in HLD
• /arckit.dld-review - Reflect decision in DLD
• /arckit.traceability - Verify decision traceability