Architecture Decisions#

Every software system is shaped by hundreds of decisions — technology choices, structural patterns, integration approaches. The best teams make these decisions explicitly, traceably, and reversibly. Architecture Decision Records (ADRs) are the primary tool for this discipline.

Architecture Decision Records (ADRs)#

An ADR documents one significant architectural decision along with its context, rationale, and consequences.

Standard Format#

# ADR-001: Use PostgreSQL for order storage

## Status
Accepted (2024-03-15)

## Context
The orders service needs persistent storage supporting:
- ACID transactions for financial data
- Complex queries for reporting
- High write throughput (10K orders/hour peak)

We considered PostgreSQL, DynamoDB, and MongoDB.

## Decision
We will use PostgreSQL (via AWS RDS).

## Consequences
### Positive
- Strong consistency guarantees
- Rich query capabilities (JOIN, aggregates)
- Team expertise exists

### Negative
- Vertical scaling limits (vs DynamoDB)
- Operational overhead (backups, failover)
- Schema migrations required for changes

### Risks
- May need read replicas at 100K orders/hour

ADR Lifecycle#

Where to Store ADRs#

Recommendation: Store in the repo for service-specific decisions; use a central wiki for cross-cutting decisions.

Decision Criteria#

Not all decisions deserve equal rigor. Evaluate decisions on three axes:

Reversibility#

Blast Radius#

Alignment#

Decisions should align with:

• Business strategy — Does this support where the company is going?
• Technical strategy — Is this consistent with the tech radar?
• Team capabilities — Can the team build and maintain this?
• Existing decisions — Does this contradict prior ADRs?

Fitness Functions#

Fitness functions are automated checks that validate whether the system still meets its architectural goals over time.

Types#

Examples#

# Deployment fitness function
- name: "No service takes > 15 minutes to deploy"
  metric: deployment_duration_p95
  threshold: "< 900s"
  frequency: per_deployment

# Coupling fitness function  
- name: "No service has > 3 synchronous dependencies"
  check: dependency_graph_analysis
  threshold: "max_sync_deps <= 3"
  frequency: weekly

# Security fitness function
- name: "No critical CVEs in production"
  check: vulnerability_scan
  threshold: "critical_count == 0"
  frequency: daily

Architecture Tests (Code-Level)#

// ArchUnit (Java) — enforce layering
@ArchTest
static final ArchRule layerRule = layeredArchitecture()
    .layer("Controller").definedBy("..controller..")
    .layer("Service").definedBy("..service..")
    .layer("Repository").definedBy("..repository..")
    .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
    .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
    .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service");

# Python — enforce no circular imports
# deptry / import-linter
[importlinter]
root_package = myapp
[importlinter:contract:layers]
name = Layered architecture
type = layers
layers =
    myapp.api
    myapp.service
    myapp.repository

Evolutionary Architecture#

Architecture should evolve incrementally rather than be designed upfront for all future needs.

Principles#

Guided Evolution#

              ┌─────────────────────────────────────────┐
              │  Fitness Functions (automated guardrails) │
              └─────────────────┬───────────────────────┘
                                │
    Start ──→ [Simple] ──→ [Modular] ──→ [Distributed] ──→ [Adaptive]
                │               │              │                │
            Monolith      Modular mono    Microservices    Event-driven

Avoiding Evolutionary Traps#

Tech Radar#

A tech radar communicates the organization’s technology strategy:

Example Entries#

Maintaining the Radar#

• Review quarterly with engineering leads
• Any engineer can propose additions/movements
• Decisions to move items require lightweight ADR
• Publish openly — transparency drives adoption

Architecture Reviews#

When to Review#

Lightweight Architecture Review#

## Review Checklist

### Structural
- [ ] Clear bounded context / responsibility
- [ ] Dependencies explicit and minimal
- [ ] No circular dependencies
- [ ] Data ownership clear

### Quality Attributes
- [ ] Scalability approach documented
- [ ] Failure modes identified
- [ ] Performance targets defined
- [ ] Security model documented

### Evolutionary
- [ ] Decision reversibility assessed
- [ ] ADR written for significant decisions
- [ ] Fitness functions defined
- [ ] Migration path from current state clear

Communicating Decisions#

Decisions are worthless if the team doesn’t know about them.

Communication Channels#

Decision Announcement Template#

## 📐 Architecture Decision: [Title]

**What:** [One-line summary of the decision]
**Why:** [Business/technical driver in plain language]
**Impact:** [Who needs to change behavior and how]
**ADR:** [Link to full ADR]
**Questions:** [Contact person or channel]

Common Mistakes#

Key Takeaways#

1. Write ADRs for any decision that is hard to reverse or affects multiple teams.
2. Classify decisions by reversibility and blast radius — govern accordingly.
3. Fitness functions automate architectural compliance — don’t rely on manual reviews alone.
4. Architecture should evolve incrementally — avoid big upfront design.
5. A tech radar communicates strategy; keep it alive with quarterly reviews.
6. Communicate decisions through multiple channels — an ADR nobody reads is worthless.
7. The goal is not perfect architecture but informed, traceable, reversible decisions.