​

Architecture Decision Record (ADR)

​

Command

arckit adr "<decision topic>"

​

Description

​

Arguments

• Decision topic: Subject of the architectural decision (e.g., ‘API gateway selection’, ‘database platform’)

​

When to Use

• Significant architectural decisions affecting structure, behavior, quality
• Technology choices (databases, frameworks, cloud services)
• Integration patterns and protocols
• Security and compliance approaches
• Deployment and infrastructure decisions
• Data management and privacy decisions

​

Do NOT Create ADR For

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

​

Required Context

• Architecture Principles (ARC-000-PRIN-*.md) - MANDATORY
• Requirements (ARC--REQ-.md) - MANDATORY
• Risk Register (ARC--RISK-.md) - Recommended
• Research (ARC--RSCH-.md) - Recommended
• Wardley Map (WARD) - For evolution context

​

Interactive Configuration

1. Escalation Level:
   • Team - Local implementation
   • Cross-team - Integration patterns
   • Department (Recommended) - Technology standards
   • Cross-government - National infrastructure
2. Options Count:
   • 3 options (Recommended) - Do Nothing + 2 alternatives
   • 2 options - Quick decision
   • 4+ options - Comprehensive analysis

​

ADR Structure

​

Context and Problem Statement

• Problem description
• Business context (link to BR requirements)
• Technical context (link to FR/NFR)
• Regulatory context (GDPR, GDS Service Standard)

​

Decision Drivers (Forces)

• Performance, scalability, maintainability
• Link to NFR requirements
• Reference architecture principles

• Cost, time to market, risk reduction
• Link to BR requirements and stakeholder goals

• GDS Service Standard points
• Technology Code of Practice (TCoP)
• NCSC Cyber Security
• UK GDPR requirements

​

Considered Options

• Description and implementation approach
• Wardley Evolution Stage (Genesis/Custom/Product/Commodity)
• ✅ Good (Pros) - Benefits, requirements met
• ❌ Bad (Cons) - Drawbacks, trade-offs
• Cost Analysis (CAPEX, OPEX, 3-year TCO)
• GDS Service Standard impact

​

Decision Outcome

• Chosen option
• Y-Statement (structured justification)
• Justification with evidence
• Stakeholder consensus or dissent

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

​

Consequences

• Positive: Benefits, capabilities, compliance
• Negative: Trade-offs, limitations, technical debt
• Neutral: Changes needed (training, infrastructure)
• Risks and Mitigations: Table with risk, likelihood, impact

​

Validation & Compliance

• Implementation verification (HLD, DLD, code review)
• Monitoring & observability
• Compliance verification (GDS, TCoP, security, GDPR)

​

Escalation Levels

​

Output

• Sequential: ADR-001, ADR-002, ADR-003
• Never reuse numbers
• Superseded ADRs remain with updated status

​

Status Transitions

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

​

Related Commands

• arckit hld-review - Reflect decision in HLD
• arckit diagram - Update architecture diagrams
• arckit traceability - Update traceability matrix

​

Example

arckit adr "Use PostgreSQL for transactional data persistence"

• Options: PostgreSQL, MySQL, Do Nothing
• Decision drivers from requirements
• Cost analysis
• Compliance mapping
• Implementation plan

​

Next Steps

1. Stakeholder review and approval
2. Update status to “Accepted”
3. Reflect decision in HLD/DLD
4. Update architecture diagrams
5. Implement decision
6. Verify with testing
7. Schedule ADR review (3-6 months)