Module 5: Architecture Decision Records & Reviews: Case Studies
These case studies make architecture governance practical. A decision is not done when a meeting ends. It is done when the context, decision, consequences, review evidence, and follow-up checks are visible to future engineers.
How To Use These Case Studies
- Decide whether the issue is architecturally significant.
- Write the decision in context, decision, consequences form.
- Identify reversibility and review depth.
- Produce the required artifact.
- Add a follow-up check so the decision can age honestly.
Case Study 1: Database Choice With No Memory
Scenario: A team chose PostgreSQL for a product three years ago. New engineers ask why not DynamoDB. Nobody remembers the original constraints, so the debate restarts every quarter.
Source anchor: The Architectural Decision Records site defines an architectural decision as a justified design choice addressing an architecturally significant requirement. the ADR site for Michael Nygard architecture decision records official ADR GitHub.
Module concepts:
- ADR
- context
- decision
- consequences
- decision memory
- status lifecycle
Wrong Approach
"We decided in a meeting; everyone knows why."
People leave, constraints change, and memory decays.
Better Approach
Write the ADR:
Context:
relational constraints, reporting queries, team SQL skill, transactional workflows
Decision:
use PostgreSQL as the system of record
Consequences:
strong relational modeling
simpler transactions
scaling plan must handle vertical limits and read replicas
revisit if write volume or access pattern changes
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| no ADR | fastest today | repeated debate |
| ADR | durable reasoning | writing and maintenance |
| long design doc only | detailed context | hard to scan later |
| decision log + links | concise memory | must keep status current |
Failure Mode
The same architecture debate consumes engineering time because the team cannot distinguish expired assumptions from forgotten reasoning.
Required Artifact
Write an ADR for one capstone database choice with status, context, decision, consequences, and revisit trigger.
Project / Capstone Connection
Every capstone should include at least three ADRs for major decisions.
Case Study 2: Review Method Too Heavy For The Risk
Scenario: A team wants a full architecture review for a small internal admin page. Another team ships a cross-region payment architecture after a 30-minute meeting. The review depth is backwards.
Source anchor: SEI's Architecture Tradeoff Analysis Method collection describes ATAM as a method for evaluating architecture against quality-attribute goals and exposing risks, tradeoffs, and sensitivity points. the SEI ATAM collection for SEI ATAM Architecture Tradeoff Analysis Method official.
Module concepts:
- ATAM
- risk-driven review
- review depth
- quality attributes
- sensitivity point
- tradeoff point
Wrong Approach
"All architecture reviews should use the same process."
Review weight should follow architectural risk.
Better Approach
Scale review:
Low risk:
peer review + checklist
Medium risk:
ADR + focused review on top 3 qualities
High risk:
structured review, scenarios, risk matrix, stakeholder participation
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| no review | speed | hidden risk |
| lightweight review | good default | can miss systemic risk |
| ATAM-style review | deep quality tradeoff analysis | time and facilitation cost |
| governance board for all | consistency | bottleneck and resentment |
Failure Mode
The organization either rubber-stamps risky decisions or smothers low-risk work.
Required Artifact
Create a review-depth rubric with risk factors and required outputs.
Project / Capstone Connection
Capstone reviews should state why their review method matches risk.
Case Study 3: ADR Without Consequences
Scenario: An ADR says "Use Kafka for events" and lists the decision, but no consequences. Six months later, nobody planned schema governance, replay, idempotency, dead-letter handling, or local development.
Source anchor: MADR and ADR guidance emphasize documenting context, decision, considered options, and consequences so decisions remain useful after acceptance. See MADR template and Architectural Decision Records.
Module concepts:
- consequences
- options considered
- acceptance criteria
- architecture debt
- operational readiness
Wrong Approach
"The ADR records what we chose. That is enough."
The future needs to know the cost of the choice, not only the winner.
Better Approach
Write consequences as obligations:
Positive:
async integration and replayable event history
Negative:
schema registry required
idempotent consumers required
DLQ operations required
local development stack heavier
Follow-up:
event contract tests in CI
runbook before production launch
Tradeoff Table
| ADR section | If missing |
|---|---|
| context | decision looks arbitrary |
| options | rejected paths are rediscovered |
| consequences | obligations are invisible |
| status | stale decisions look current |
| follow-up | decision is never verified |
Failure Mode
The team accepts an architecture decision but does not fund the work that makes it safe.
Required Artifact
Revise a weak ADR by adding options, consequences, follow-up checks, and supersession criteria.
Project / Capstone Connection
Capstone ADRs should include negative consequences, not only benefits.
Case Study 4: Architecture Drift After A Good Decision
Scenario: An ADR says domain code must not depend on web framework classes. A year later, controllers, validators, and framework-specific exceptions appear inside domain packages.
Source anchor: Thoughtworks' evolutionary architecture material emphasizes fitness functions as automated governance for architecture characteristics. See Thoughtworks: Building Evolutionary Architectures.
Module concepts:
- architecture drift
- fitness function
- automated governance
- decision follow-through
- dependency rule
Wrong Approach
"We documented the rule, so the architecture is protected."
Documentation does not stop drift.
Better Approach
Add checks:
Rule:
domain package must not import web framework
Fitness function:
dependency test fails if domain imports framework namespaces
Review:
exceptions require ADR update
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| documentation only | easy | drift invisible |
| CI dependency checks | continuous enforcement | maintenance and exceptions |
| manual review | contextual judgment | inconsistent coverage |
| scheduled ADR review | catches aging decisions | needs ownership |
Failure Mode
The decision is still "accepted" while the codebase has contradicted it for months.
Required Artifact
Write one architecture fitness function and the ADR status rule that changes if the check is repeatedly bypassed.
Project / Capstone Connection
Capstone architecture decisions should have at least one executable or reviewable follow-up check.
Case Study 5: Review Meeting Produces Opinions, Not Decisions
Scenario: A team reviews a proposal to split billing into a service. The meeting has strong opinions but no captured quality attributes, risks, decisions, or open questions. Two weeks later, attendees remember different outcomes.
Source anchor: SEI ATAM guidance and risk-driven architecture practices emphasize scenarios, risks, tradeoffs, and documented outputs. See SEI ATAM collection.
Module concepts:
- architecture review
- risk register
- quality scenarios
- decision capture
- action ownership
Wrong Approach
"A review is a meeting where senior engineers give feedback."
A review should produce artifacts.
Better Approach
Capture:
Decision:
accepted / rejected / needs work
Top risks:
data migration
payment reconciliation
operational ownership
Tradeoffs:
service autonomy vs distributed transactions
Follow-up:
owner, date, evidence required
Tradeoff Table
| Review output | Why it matters |
|---|---|
| decision/status | prevents ambiguous outcomes |
| risks | focuses follow-up work |
| scenarios | grounds quality discussion |
| action owners | makes review actionable |
| ADR updates | preserves memory |
Failure Mode
Architecture review becomes a ritual with no operational effect.
Required Artifact
Create a review record template with decision, risks, tradeoffs, scenarios, action items, and ADR links.
Project / Capstone Connection
The final capstone defense should include a review record, not only polished diagrams.
Source Map
| Source | Use it for |
|---|---|
| Architectural Decision Records | ADR purpose and decision framing |
| MADR template | structured ADR sections |
| SEI ATAM collection | quality-attribute review, risks, tradeoffs |
| Thoughtworks: Building Evolutionary Architectures | fitness functions and architecture governance |
Completion Standard
- At least three artifacts are completed.
- At least one ADR includes negative consequences and revisit criteria.
- At least one review rubric scales by risk.
- At least one decision has an executable or reviewable follow-up check.
- At least one review record captures risks, tradeoffs, and action owners.