williamzujkowski/Architecture Decision Framework

Purpose & When-To-Use

Invoke when:

• New project requires architecture design from requirements
• Existing system needs architecture refactoring or migration
• Technical debt analysis reveals architectural anti-patterns
• Cross-team alignment needed on architecture direction
• Compliance/audit requires documented architecture decisions

Outputs: Complete ADR, trade-off analysis, C4 diagrams, pattern recommendations.

Pre-Checks

1. Normalize time: Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601).
2. Validate inputs:

• decision_context is non-empty and describes business/technical problem
• constraints include at least one quality attribute (performance, security, scalability, maintainability)
• stakeholders list includes technical decision-makers

1. Source freshness: Verify authoritative sources accessed at NOW_ET:

• ADR templates from adr.github.io (accessed 2025-10-25T21:30:36-04:00)
• Fowler architecture patterns (accessed 2025-10-25T21:30:36-04:00)
• C4 model specification (accessed 2025-10-25T21:30:36-04:00)
• ATAM from SEI/CMU (accessed 2025-10-25T21:30:36-04:00)

Procedure

T1: Quick Decision (≤2k tokens)

When: Clear pattern match, minimal trade-offs, single stakeholder concern.

1. Pattern Match: Map decision_context to one of:

• Layered: UI/Business/Data separation, traditional monoliths
• Hexagonal (Ports & Adapters): Domain isolation, testability focus
• Event-Driven: Asynchronous workflows, decoupled services
• CQRS: Read/write separation, complex domain models

1. Quick ADR (Nygard format):

markdown # ADR-NNN: Decision Title]

Status: Proposed | Accepted | Deprecated | Superseded

## Context Business/technical context in 2-3 sentences]

## Decision Pattern/approach chosen]

## Consequences Positive: 1-2 benefits] Negative: 1-2 drawbacks]

1. Stop if: Decision is straightforward with clear pattern fit and < 3 alternatives.

T2: Extended Analysis (≤6k tokens)

When: Multiple patterns viable, significant trade-offs, cross-team impact.

1. Pattern Evaluation Matrix:

For each candidate pattern (Layered, Hexagonal, Event-Driven, CQRS):

• Quality Attributes (score 1-5): Performance, Scalability, Maintainability, Testability, Security
• Fit to Context: How well pattern addresses decision_context
• Migration Cost: Effort to implement from current_architecture
• Team Skill Alignment: Existing team expertise

1. ATAM Trade-Off Analysis:

• Scenarios: Create 3-5 quality attribute scenarios (e.g., "System must handle 10k concurrent users with <500ms latency")
• Sensitivity Points: Decisions heavily impacting quality attributes
• Trade-Off Points: Conflicts between quality attributes (e.g., performance vs. maintainability)
• Risks: Architectural decisions with uncertain outcomes
• Non-Risks: Sound decisions with low uncertainty

1. Y-Statement ADR (extended format):

In the context of [functional requirement or component], facing [non-functional requirement or quality concern], we decided for [chosen pattern/approach] and neglected [alternative 1], [alternative 2] to achieve [benefits and requirement satisfaction], accepting that [drawbacks and consequences].

1. C4 Context Diagram (Level 1):

• System boundary and external dependencies
• Primary users and external systems
• Key interactions and data flows

1. Pattern Combination Recommendations:

Common hybrid patterns:

• Layered + Hexagonal: Traditional layers with domain isolation
• Event-Driven + CQRS: Event sourcing with read/write separation
• Hexagonal + Event-Driven: Ports/adapters with async messaging

T3: Deep Dive (≤12k tokens)

When: Greenfield complex system, high-risk migration, multiple conflicting stakeholders.

1. Full MADR (Markdown ADR):

Include: Context, Decision Drivers, Considered Options, Decision Outcome, Pros/Cons, Links, Technical Story.

1. Complete C4 Model:

• Level 1 Context: System in environment
• Level 2 Container: Runtime executables/databases
• Level 3 Component: Internal component structure
• Optional Level 4 Code: Class diagrams for critical components

1. Comprehensive Trade-Off Analysis:

• ATAM full workshop simulation: Utility tree with prioritized quality attributes
• Cost-benefit matrix: Implementation cost vs. benefit for each pattern
• Risk mitigation strategies: For each identified risk
• Migration roadmap: Phased approach if migrating from current_architecture

1. Pattern Catalog Deep Dive:

For Layered, Hexagonal, Event-Driven, CQRS:

• When to use: Detailed triggers and anti-triggers
• Reference implementations: Links to open-source examples
• Common pitfalls: Anti-patterns and failure modes
• Evolution paths: How pattern adapts to changing requirements

Decision Rules

1. Pattern Selection Thresholds:

• Layered: Use when <= 3 quality attributes critical, monolith acceptable, team traditional
• Hexagonal: Use when testability/domain isolation > deployment complexity
• Event-Driven: Use when asynchrony required, loose coupling critical, eventual consistency acceptable
• CQRS: Use when read/write patterns diverge significantly, complex domain model, scalability critical

1. Abort Conditions:

• decision_context is vague or lacks quality attribute constraints → Request clarification
• No authoritative sources available for claimed pattern benefits → Defer decision
• Stakeholder consensus impossible on quality attribute priorities → Escalate

1. Ambiguity Handling:

• If 2+ patterns score within 10% on evaluation matrix → Recommend hybrid or phased approach
• If current_architecture migration cost > 2x implementation benefit → Recommend incremental strangler pattern

Output Contract

Required Fields:

json
{
  "adr": {
    "format": "nygard | madr | y-statement",
    "title": "ADR-NNN: [Title]",
    "status": "proposed | accepted | deprecated | superseded",
    "context": "string",
    "decision": "string",
    "consequences": ["array of strings"],
    "date": "ISO-8601",
    "author": "string"
  },
  "trade_off_analysis": {
    "method": "atam | cost-benefit | quality-attribute-matrix",
    "patterns_evaluated": ["array of pattern names"],
    "sensitivity_points": ["array"],
    "trade_off_points": ["array"],
    "risks": ["array"],
    "recommendation": "string"
  },
  "c4_diagrams": {
    "context": "PlantUML or Mermaid syntax",
    "container": "PlantUML or Mermaid syntax (optional)",
    "component": "PlantUML or Mermaid syntax (optional)"
  },
  "pattern_recommendation": {
    "primary": "pattern name",
    "rationale": "string (≤200 chars)",
    "alternatives": ["array of pattern names"],
    "migration_strategy": "greenfield | strangler | big-bang | phased"
  }
}

Constraints:

• ADR title ≤ 100 chars
• Context section ≤ 500 words
• C4 diagrams in PlantUML or Mermaid format
• All external references must have access date = NOW_ET

Examples

yaml
# T2 Example: Microservices API Gateway Decision
decision_context: "E-commerce platform migrating from monolith to microservices"
constraints:
  - performance: "< 200ms latency for 95th percentile"
  - scalability: "Handle 50k concurrent users"
  - maintainability: "Independent team deployment"

output:
  adr_format: y-statement
  content: |
    In the context of migrating monolithic e-commerce to microservices,
    facing the need for unified API entry point with <200ms latency,
    we decided for API Gateway pattern with event-driven backend
    and neglected direct client-to-service calls, service mesh only,
    to achieve centralized auth/rate-limiting and loose coupling,
    accepting that gateway becomes potential bottleneck requiring HA design.

  trade_off_analysis:
    patterns_evaluated: [hexagonal, event-driven, cqrs]
    recommendation: "Hexagonal (services) + Event-Driven (inter-service)"
    trade_offs:
      - "Performance vs Maintainability: Event async adds latency but improves decoupling"
      - "Complexity vs Scalability: More components but independent scaling"

Quality Gates

1. Token Budget:

• T1 ≤ 2,000 tokens (pattern match + simple ADR)
• T2 ≤ 6,000 tokens (ATAM + Y-statement + C4 context)
• T3 ≤ 12,000 tokens (full MADR + complete C4 + deep trade-off)

1. Validation:

• All ADRs include: title, status, context, decision, consequences
• Trade-off analysis cites specific quality attributes
• Pattern recommendations linked to authoritative sources with NOW_ET dates
• C4 diagrams validate with PlantUML/Mermaid parsers

1. Auditability:

• Decision rationale traceable to decision_context and constraints
• All claimed pattern benefits cite Fowler, SEI, or peer-reviewed sources
• Rejected alternatives documented with rejection rationale

Resources

ADR Templates & Practices:

• ADR GitHub Organization: https://adr.github.io/ (accessed 2025-10-25T21:30:36-04:00)
• MADR Templates: https://adr.github.io/adr-templates/ (accessed 2025-10-25T21:30:36-04:00)
• Y-Statements Guide: https://medium.com/olzzio/y-statements-10eb07b5a177 (accessed 2025-10-25T21:30:36-04:00)

Architecture Patterns:

• Martin Fowler Architecture: https://martinfowler.com/architecture (accessed 2025-10-25T21:30:36-04:00)
• Event-Driven Patterns: https://martinfowler.com/articles/201701-event-driven.html (accessed 2025-10-25T21:30:36-04:00)
• Hexagonal Architecture: https://alistair.cockburn.us/hexagonal-architecture (accessed 2025-10-25T21:30:36-04:00)

C4 Model:

• C4 Model Official Site: https://c4model.com/ (accessed 2025-10-25T21:30:36-04:00)
• C4 Diagrams Guide: https://c4model.com/diagrams (accessed 2025-10-25T21:30:36-04:00)

Trade-Off Analysis:

• ATAM (SEI/CMU): https://www.sei.cmu.edu/library/architecture-tradeoff-analysis-method-collection/ (accessed 2025-10-25T21:30:36-04:00)
• Architecture Decision Making: https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html (accessed 2025-10-25T21:30:36-04:00)