Architecture Decision
type: diagnostic
mode: evaluative
triggers:
- "architecture decision"
- "ADR"
- "design pattern selection"
- "technology choice"
- "architectural trade-offs"
Purpose
Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.
Core Principle
Context drives decisions. No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.
The Trade-off Triangle
Every architectural decision involves trade-offs:
| Vertex |
Maximized By |
Cost |
| Simplicity |
Monolith, sync communication, single DB |
Scalability limits |
| Flexibility |
Microservices, event-driven, plugins |
Complexity overhead |
| Performance |
Caching, denormalization, optimized code |
Maintainability |
Balance Strategies:
- Start simple, add complexity as needed
- Measure before optimizing
- Use abstractions to defer decisions
- Evolve incrementally
Quality Attributes
Architecture primarily addresses non-functional requirements:
Performance
- Metrics: Response time (p50, p95, p99), throughput, resource utilization
- Tactics: Caching, load balancing, async processing
Scalability
- Dimensions: Horizontal (more machines), vertical (more resources), elastic
- Patterns: Stateless services, sharding, event streaming
Reliability
- Metrics: Uptime, MTBF, MTTR
- Patterns: Circuit breakers, retries, redundancy
Security
- Concerns: AuthN/AuthZ, encryption, audit logging
- Patterns: Zero trust, defense in depth, least privilege
Maintainability
- Factors: Readability, modularity, testability
- Patterns: Clean architecture, DDD, SOLID
Context-Pattern Mapping
Team Context
| Context |
Preferred Patterns |
Avoid |
| Small team |
Monolith, vertical slices, shared DB |
Microservices, complex abstractions |
| Multiple teams |
Service boundaries, API contracts, Conway alignment |
Shared state, tight coupling |
Domain Context
| Context |
Preferred Patterns |
Reasoning |
| High complexity |
DDD, bounded contexts, event sourcing |
Complex domains need explicit modeling |
| Low complexity |
Transaction script, active record, CRUD |
Simple domains don't justify complexity |
Scale Context
| Context |
Preferred Patterns |
Reasoning |
| Startup |
Monolith first, vertical scaling |
Optimize for development speed |
| Enterprise |
Service mesh, horizontal scaling |
Optimize for operational scale |
Decision Matrix Template
| Option |
Consistency |
Flexibility |
Scalability |
Complexity |
Cost |
Total |
| Option A |
5 |
2 |
3 |
2 |
3 |
15 |
| Option B |
3 |
5 |
4 |
3 |
3 |
18 |
| Option C |
2 |
3 |
5 |
1 |
2 |
13 |
Weight factors based on context priorities.
Architecture Decision Record (ADR) Template
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded]
## Context
[What is the situation requiring a decision?]
### Requirements
- [Requirement 1]
- [Requirement 2]
### Constraints
- [Constraint 1]
- [Constraint 2]
## Decision
[What is the decision?]
### Justification
- [Reason 1]
- [Reason 2]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Drawback 1]
- [Drawback 2]
## Alternatives Considered
### [Alternative 1]
Reason rejected: [Why]
### [Alternative 2]
Reason rejected: [Why]
Risk Assessment
Risk Categories
| Category |
Examples |
Mitigation |
| Technical |
Unproven tech, performance bottlenecks |
POCs, load testing, fallback plans |
| Business |
Vendor lock-in, skill availability |
Abstraction layers, training |
| Operational |
Deployment complexity, monitoring gaps |
Automation, observability |
Risk Matrix
|
Low Impact |
High Impact |
| High Probability |
Automate mitigation |
Must address immediately |
| Low Probability |
Accept or ignore |
Contingency planning |
Architectural Refactoring Patterns
Branch by Abstraction
- Create abstraction over current implementation
- Implement new solution behind abstraction
- Switch to new implementation
- Remove old implementation
Strangler Fig
- Identify boundary
- Implement new solution for new features
- Gradually migrate old features
- Retire old system
Parallel Run
- Implement new solution
- Run both old and new
- Compare results
- Switch when confident
Technical Debt Management
Debt Categories
| Type |
Examples |
Payment Strategy |
| Design |
Missing abstractions, tight coupling |
Refactoring sprints |
| Code |
Duplication, complexity, poor naming |
Continuous cleanup |
| Test |
Missing tests, flaky tests |
Test improvement |
| Documentation |
Missing docs, outdated diagrams |
Documentation sprints |
Metrics
- Debt ratio: Debt work / Total work (target < 20%)
- Interest rate: Extra effort due to debt
- Debt ceiling: Maximum acceptable debt (stop features if exceeded)
Anti-Patterns
Big Ball of Mud
Symptoms: No clear structure, everything depends on everything
Remedy: Identify boundaries, extract modules, establish interfaces
Distributed Monolith
Symptoms: Services must deploy together, sync chains, shared DBs
Remedy: Merge related services, async communication, separate DBs
Golden Hammer
Symptoms: One solution for all problems, force-fitting patterns
Remedy: Learn alternatives, evaluate objectively, prototype options
Integration Points
Inbound:
- When making technology choices
- When designing new systems
- When refactoring existing systems
Outbound:
- To implementation planning
- To technical debt tracking
- To team documentation
Complementary:
code-review: For implementation validationtask-decomposition: For breaking down architectural workrequirements-analysis: For understanding constraints
1---2name: architecture-decision3description: Architecture Decision4---5# Architecture Decision67type: diagnostic8mode: evaluative9triggers:10 - "architecture decision"11 - "ADR"12 - "design pattern selection"13 - "technology choice"14 - "architectural trade-offs"1516## Purpose1718Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.1920## Core Principle2122**Context drives decisions.** No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.2324---2526## The Trade-off Triangle2728Every architectural decision involves trade-offs:2930| Vertex | Maximized By | Cost |31|--------|--------------|------|32| **Simplicity** | Monolith, sync communication, single DB | Scalability limits |33| **Flexibility** | Microservices, event-driven, plugins | Complexity overhead |34| **Performance** | Caching, denormalization, optimized code | Maintainability |3536**Balance Strategies:**37- Start simple, add complexity as needed38- Measure before optimizing39- Use abstractions to defer decisions40- Evolve incrementally4142---4344## Quality Attributes4546Architecture primarily addresses non-functional requirements:4748### Performance49- Metrics: Response time (p50, p95, p99), throughput, resource utilization50- Tactics: Caching, load balancing, async processing5152### Scalability53- Dimensions: Horizontal (more machines), vertical (more resources), elastic54- Patterns: Stateless services, sharding, event streaming5556### Reliability57- Metrics: Uptime, MTBF, MTTR58- Patterns: Circuit breakers, retries, redundancy5960### Security61- Concerns: AuthN/AuthZ, encryption, audit logging62- Patterns: Zero trust, defense in depth, least privilege6364### Maintainability65- Factors: Readability, modularity, testability66- Patterns: Clean architecture, DDD, SOLID6768---6970## Context-Pattern Mapping7172### Team Context7374| Context | Preferred Patterns | Avoid |75|---------|-------------------|-------|76| **Small team** | Monolith, vertical slices, shared DB | Microservices, complex abstractions |77| **Multiple teams** | Service boundaries, API contracts, Conway alignment | Shared state, tight coupling |7879### Domain Context8081| Context | Preferred Patterns | Reasoning |82|---------|-------------------|-----------|83| **High complexity** | DDD, bounded contexts, event sourcing | Complex domains need explicit modeling |84| **Low complexity** | Transaction script, active record, CRUD | Simple domains don't justify complexity |8586### Scale Context8788| Context | Preferred Patterns | Reasoning |89|---------|-------------------|-----------|90| **Startup** | Monolith first, vertical scaling | Optimize for development speed |91| **Enterprise** | Service mesh, horizontal scaling | Optimize for operational scale |9293---9495## Decision Matrix Template9697| Option | Consistency | Flexibility | Scalability | Complexity | Cost | Total |98|--------|-------------|-------------|-------------|------------|------|-------|99| Option A | 5 | 2 | 3 | 2 | 3 | 15 |100| Option B | 3 | 5 | 4 | 3 | 3 | 18 |101| Option C | 2 | 3 | 5 | 1 | 2 | 13 |102103**Weight factors based on context priorities.**104105---106107## Architecture Decision Record (ADR) Template108109```markdown110# ADR-[NUMBER]: [TITLE]111112## Status113[Proposed | Accepted | Deprecated | Superseded]114115## Context116[What is the situation requiring a decision?]117118### Requirements119- [Requirement 1]120- [Requirement 2]121122### Constraints123- [Constraint 1]124- [Constraint 2]125126## Decision127[What is the decision?]128129### Justification130- [Reason 1]131- [Reason 2]132133## Consequences134135### Positive136- [Benefit 1]137- [Benefit 2]138139### Negative140- [Drawback 1]141- [Drawback 2]142143## Alternatives Considered144145### [Alternative 1]146Reason rejected: [Why]147148### [Alternative 2]149Reason rejected: [Why]150```151152---153154## Risk Assessment155156### Risk Categories157158| Category | Examples | Mitigation |159|----------|----------|------------|160| **Technical** | Unproven tech, performance bottlenecks | POCs, load testing, fallback plans |161| **Business** | Vendor lock-in, skill availability | Abstraction layers, training |162| **Operational** | Deployment complexity, monitoring gaps | Automation, observability |163164### Risk Matrix165166| | Low Impact | High Impact |167|---|-----------|-------------|168| **High Probability** | Automate mitigation | Must address immediately |169| **Low Probability** | Accept or ignore | Contingency planning |170171---172173## Architectural Refactoring Patterns174175### Branch by Abstraction1761. Create abstraction over current implementation1772. Implement new solution behind abstraction1783. Switch to new implementation1794. Remove old implementation180181### Strangler Fig1821. Identify boundary1832. Implement new solution for new features1843. Gradually migrate old features1854. Retire old system186187### Parallel Run1881. Implement new solution1892. Run both old and new1903. Compare results1914. Switch when confident192193---194195## Technical Debt Management196197### Debt Categories198199| Type | Examples | Payment Strategy |200|------|----------|------------------|201| **Design** | Missing abstractions, tight coupling | Refactoring sprints |202| **Code** | Duplication, complexity, poor naming | Continuous cleanup |203| **Test** | Missing tests, flaky tests | Test improvement |204| **Documentation** | Missing docs, outdated diagrams | Documentation sprints |205206### Metrics207- **Debt ratio:** Debt work / Total work (target < 20%)208- **Interest rate:** Extra effort due to debt209- **Debt ceiling:** Maximum acceptable debt (stop features if exceeded)210211---212213## Anti-Patterns214215### Big Ball of Mud216**Symptoms:** No clear structure, everything depends on everything217**Remedy:** Identify boundaries, extract modules, establish interfaces218219### Distributed Monolith220**Symptoms:** Services must deploy together, sync chains, shared DBs221**Remedy:** Merge related services, async communication, separate DBs222223### Golden Hammer224**Symptoms:** One solution for all problems, force-fitting patterns225**Remedy:** Learn alternatives, evaluate objectively, prototype options226227---228229## Integration Points230231**Inbound:**232- When making technology choices233- When designing new systems234- When refactoring existing systems235236**Outbound:**237- To implementation planning238- To technical debt tracking239- To team documentation240241**Complementary:**242- `code-review`: For implementation validation243- `task-decomposition`: For breaking down architectural work244- `requirements-analysis`: For understanding constraints
jwynia