← Back to all projects

ARCHITECTURE DECISION RECORDS MASTERY

In 2011, Michael Nygard proposed the ADR as a way to capture architectural decisions in a format that lives with the code. Before this, architecture was often buried in 100-page PDF documents that no one read or understood three months after they were written.

Learn Architecture Decision Records (ADRs): From Documentation to Decision Science

Goal: Deeply understand the art and science of Architectural Decision Records. You will move beyond simple templates to mastering the capture of context, the evaluation of alternatives, the identification of hard constraints, and the crucial distinction between reversible and irreversible decisions. By the end, you’ll be able to build workflows that turn ADRs into a living, breathing institutional memory that prevents technical debt and architectural drift.

Why ADRs Matter

In 2011, Michael Nygard proposed the ADR as a way to capture “architectural decisions” in a format that lives with the code. Before this, architecture was often buried in 100-page PDF documents that no one read or understood three months after they were written.

Software is a series of trade-offs. ADRs matter because:

  • Context is Perishable: Six months from now, no one will remember why you chose NoSQL over Postgres.
  • The “Chesterton’s Fence” Problem: Developers often see “weird” code and delete it, not realizing it was a specific architectural fix for a rare edge case.
  • Onboarding Acceleration: New engineers can read the history of the system’s design rather than asking “why” 1,000 times.
  • Decision Velocity: By categorizing decisions (Reversible vs. Irreversible), teams can move faster on low-risk choices and slow down for high-stakes ones.

Core Concept Analysis

1. The Anatomy of a Decision

An ADR is not just a “log.” It is a structured narrative of a moment in time where a path was chosen.

┌──────────────────────────────────────────────────────────┐
│                    ADR [ID]: [Title]                     │
├────────────┬─────────────────────────────────────────────┤
│   STATUS   │ Proposed | Accepted | Superseded | Deprecated│
├────────────┼─────────────────────────────────────────────┤
│  CONTEXT   │ What is the problem? What are the pressures?│
│            │ What are the constraints (Time, Budget)?    │
├────────────┼─────────────────────────────────────────────┤
│ALTERNATIVES│ Option A, Option B, Option C...             │
│            │ Why were they rejected?                      │
├────────────┼─────────────────────────────────────────────┤
│  DECISION  │ We will use [X] because [Y].                │
├────────────┼─────────────────────────────────────────────┤
│CONSEQUENCE│ What do we gain? What do we lose (debt)?    │
│            │ What new problems does this create?         │
└────────────┴─────────────────────────────────────────────┘

2. One-Way vs. Two-Way Doors (Decision Type)

Inspired by Jeff Bezos’s framework, effective ADR workflows distinguish between the “cost of being wrong.”

Type 1 (One-Way Door):

  • Characteristics: Irreversible or nearly so. High cost to change.
  • Examples: Choosing a primary programming language, core database engine, or cloud provider.
  • ADR Focus: Heavy on alternatives, data-driven validation, and risk mitigation.

Type 2 (Two-Way Door):

  • Characteristics: Easily reversible. Low cost to experiment.
  • Examples: Choosing a logging library, internal API naming convention, or cache TTL.
  • ADR Focus: Speed, clarity of intent, and “exit strategy.”

3. The Decision Lifecycle

Architecture is not static. Decisions are superseded as the environment changes.

    [PROPOSED] ──────▶ [ACCEPTED] ──────┐
        │                 │             │
        │                 ▼             ▼
        └──────────▶ [SUPERSEDED]   [DEPRECATED]
                          ▲             │
                          │             │
                    [NEW DECISION] ◀────┘

4. Constraints and Trade-offs (The “Why”)

Every decision is a choice between two or more “evils” or “goods.” If there is no trade-off, it’s not an architectural decision; it’s a best practice.

  • Hard Constraints: “Must run on-prem,” “Must support 100k concurrent users.”
  • Soft Constraints: “Prefer open source,” “Should be easy for Python devs to learn.”

Concept Summary Table

Concept Cluster What You Need to Internalize
Decision Narrative An ADR is a story, not a state. You must capture the “vibe” and “pressure” of the moment so future you doesn’t judge past you unfairly.
Trade-off Analysis Architecture is the stuff that is hard to change later. Every “Yes” is a “No” to something else. If you can’t name what you’re giving up, you haven’t understood the decision.
Reversibility (Doors) Identifying “Two-Way Doors” allows the team to move fast. Identifying “One-Way Doors” ensures you don’t walk off a cliff blindly.
Superseding Decisions are versioned. An ADR should link to what it replaces, creating a traceable lineage of evolution.
Contextual Constraints Business reality (deadlines, budget, team skill) is as much an architectural constraint as technical latency.

Deep Dive Reading by Concept

This section maps each concept from above to specific book chapters for deeper understanding. Read these before or alongside the projects to build strong mental models.

Architectural Foundations

Concept Book & Chapter
What is Architecture? “Fundamentals of Software Architecture” by Mark Richards & Neal Ford — Ch. 1: “Introduction”
Architectural Thinking “Design It!” by Michael Keeling — Ch. 1: “Becoming a Software Architect”
Documenting Decisions “Software Systems Architecture” by Rozanski & Woods — Ch. 7: “The Architectural Description”

Decision Making & ADRs

Concept Book & Chapter
The ADR Format “Design It!” by Michael Keeling — Ch. 14: “Documenting Architecture Decisions”
Decision Types (1 vs 2) “The Software Architect Elevator” by Gregor Hohpe — Ch. 5: “Architecture Decisions”
The Path of Trade-offs “Clean Architecture” by Robert C. Martin — Ch. 15: “What is Architecture?”
Chesterton’s Fence “The Pragmatic Programmer” by Hunt & Thomas — Ch. 2: “A Pragmatic Approach” (Topic 10: Orthogonality)

Essential Reading Order

For maximum comprehension, read in this order:

  1. The Why (Week 1):
    • Design It! Ch. 1 & 14 (The motivation for ADRs)
    • The Software Architect Elevator Ch. 5 (Understanding decision levels)
  2. The How (Week 2):
    • Fundamentals of Software Architecture Ch. 1-2 (Building the mental model of trade-offs)
    • Clean Architecture Ch. 15 (The goal of architecture is to minimize human effort)

Project List

Projects are ordered from fundamental understanding to advanced implementations.

Project 1: The First Artifact (The Nygard Standard)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md
  • Main Programming Language: Markdown
  • Alternative Programming Languages: N/A (Standard text)
  • Coolness Level: Level 1: Pure Corporate Snoozefest
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 1: Beginner
  • Knowledge Area: Documentation / Architectural Basics
  • Software or Tool: Git / Plain Text
  • Main Book: “Design It!” by Michael Keeling

What you’ll build: A standardized ADR repository for a hypothetical project, following the strict Michael Nygard template, covering the first 5 critical decisions of a new startup.

Why it teaches ADRs: This forces you to move from “just code” to “thinking in decisions.” You will grapple with the structure of a decision and the discipline of documenting the Context before the Choice.

Core challenges you’ll face:

  • Distinguishing Context from Decision → maps to separating pressures from the choice
  • Defining Status transitions → maps to understanding the lifecycle of a document
  • Writing readable Consequences → maps to forecasting technical debt

Key Concepts:

  • Nygard Template: Documenting Architecture Decisions - Michael Nygard (Blog)
  • Architectural Significance: “Design It!” Ch. 2 - Michael Keeling

Difficulty: Beginner Time estimate: 2-4 hours Prerequisites: Basic understanding of Markdown and Git.

Real World Outcome

You will have a directory named docs/adr/ containing five .md files that tell the origin story of your system.

Example Output:

$ ls docs/adr/
0001-record-architecture-decisions.md
0002-use-python-fastapi-for-backend.md
0003-use-postgresql-for-relational-data.md
0004-monolithic-vs-microservices.md
0005-use-github-actions-for-ci.md

$ cat docs/adr/0002-use-python-fastapi-for-backend.md
# 2. Use Python FastAPI for Backend

## Status
Accepted

## Context
We need to build a high-performance API for our MVP. The team is mostly 
proficient in Python. We need automatic Swagger documentation.

## Decision
We will use FastAPI instead of Django or Flask.

## Consequences
+ High development velocity due to Pydantic integration.
- We lose the built-in Admin UI of Django.
- The team needs to learn async/await patterns.

The Core Question You’re Answering

“Can you explain why you did this without using the word ‘better’?”

Before you write any code, sit with this question. “Better” is subjective. Architecture is about specific trade-offs (Speed vs. Safety, Cost vs. Scale). If you can’t articulate the trade-off, you haven’t made an architectural decision yet.

Concepts You Must Understand First

Stop and research these before coding:

  1. The ADR Template
    • What are the mandatory fields in a Nygard ADR?
    • How does a “Superseded” status work?
    • Book Reference: “Design It!” Ch. 14 - Michael Keeling
  2. Architectural Trade-offs
    • What is the “Everything is a Trade-off” law?
    • How do you measure a consequence?
    • Book Reference: “Fundamentals of Software Architecture” Ch. 2 - Richards & Ford

Questions to Guide Your Design

Before implementing, think through these:

  1. Naming Conventions
    • Should ADRs be numbered 0001 or use timestamps?
    • What happens if two people create ADR 0005 at the same time?
  2. Audience
    • Who are you writing for? A developer 2 years from now, or a CTO next week?
    • How does the tone change based on the audience?

Thinking Exercise

The “Better” Filter

Imagine you decide to use PostgreSQL.

Write down three reasons why PostgreSQL is the choice.

  • Now, delete any bullet point that doesn’t have a corresponding “But the cost is…” or “At the expense of…”

Questions while tracing:

  • If it’s all “pro” and no “con,” is it really an architectural choice, or just a default?
  • What would make you regret this decision in 12 months?

The Interview Questions They’ll Ask

Prepare to answer these:

  1. “How do you handle architectural drift in a fast-moving team?”
  2. “Give an example of a decision you made where the ‘Consequences’ section proved to be right.”
  3. “Why keep ADRs in the repo instead of a Wiki/Confluence?”
  4. “How do you decide what is ‘architecturally significant’ enough for an ADR?”
  5. “What is the danger of not documenting rejected alternatives?”

Hints in Layers

Hint 1: Start with the Tooling Just use a text editor. Don’t worry about automation yet. Create a template file called template.md.

Hint 2: The Numbering Always start with 0001-record-architecture-decisions.md. This meta-ADR establishes the ADR process itself as the first decision.

Hint 3: The Context Focus on “forces.” What forces are pushing you? (e.g., “We only have 3 weeks to launch,” “No one knows Java”).

Hint 4: Debugging the ADR If your “Consequences” section is empty, you’re lying to yourself. Every choice has a cost. Find it.

Books That Will Help

Topic Book Chapter
ADR Rationale “Design It!” by Michael Keeling Ch. 14
Trade-off Analysis “Fundamentals of Software Architecture” by Richards & Ford Ch. 2

Project 2: The Two-Way Door (Reversibility Audit)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md
  • Main Programming Language: Markdown / YAML
  • Alternative Programming Languages: Python (for automation later)
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 2. The “Micro-SaaS / Pro Tool”
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Decision Science / Risk Management
  • Software or Tool: ADR Templates
  • Main Book: “The Software Architect Elevator” by Gregor Hohpe

What you’ll build: An enhanced ADR template that includes a mandatory “Reversibility Score” and “Exit Strategy.” You will document 3 high-stakes decisions and 3 low-stakes decisions.

Why it teaches ADRs: This teaches you to distinguish between Type 1 (One-way door) and Type 2 (Two-way door) decisions. It prevents “Analysis Paralysis” by showing that some decisions can be made quickly if the exit cost is low.

Core challenges you’ll face:

  • Defining Reversibility → maps to estimating migration effort
  • Creating an Exit Strategy → maps to decoupling through abstractions
  • Balancing Speed vs. Rigor → maps to adjusting process based on risk

Key Concepts:

  • Type 1 vs Type 2 Decisions: Jeff Bezos’s 2015 Shareholder Letter
  • Architecture as Options: “The Software Architect Elevator” Ch. 5

Difficulty: Intermediate Time estimate: 1 week (as you apply it to a real/mock project) Prerequisites: Project 1 completion.

Real World Outcome

A set of ADRs that explicitly state how hard they are to undo.

Example Output:

# 6. Use AWS S3 for Image Storage

## Status
Accepted

## Decision Type
Type 1 (One-Way Door)

## Reversibility
Low. Once we have millions of objects and hardcoded URLs in the DB, 
migration to GCP/Azure will be a multi-month project.

## Exit Strategy
We will use a internal 'Storage Service' interface. We will not use 
S3-specific features (like Lambda triggers) directly in our core logic 
to allow for a future shim layer.

The Core Question You’re Answering

“If we are wrong, how much will it cost to fix?”

This is the most important question for any architect. If the cost is $0 and 1 hour of work, stop writing the ADR and just do it. If the cost is $100k and 6 months of work, you need a very detailed ADR.

Thinking Exercise

The Migration Calculator

Take a decision: “Use MongoDB.”

  1. List all the code that will touch Mongo-specific APIs.
  2. List the data migration steps to move to SQL.
  3. Estimate the time for both.

Questions while tracing:

  • Is this a one-way door?
  • What single abstraction would turn it into a two-way door? (e.g., Repository Pattern).

Project 3: The Alternatives Graveyard

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md
  • Main Programming Language: Markdown
  • Alternative Programming Languages: N/A
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Critical Thinking / Evaluation
  • Software or Tool: Decision Matrix / Spreadsheet
  • Main Book: “Software Systems Architecture” by Rozanski & Woods

What you’ll build: A “Decision Matrix” ADR. Instead of just picking one option, you will document 3 competing technologies, rank them against 5 criteria (Latency, Developer Experience, Cost, etc.), and show exactly why the losers lost.

Why it teaches ADRs: Most ADRs fail because they only show the winner. This project teaches you to document the “Rejected” options, which is the most valuable part of an ADR for future skeptics.

Core challenges you’ll face:

  • Objective Criteria Selection → maps to identifying what actually matters
  • Fair Comparison → maps to avoiding “Straw Man” arguments for rejected options
  • Visualizing Trade-offs → maps to using tables effectively in Markdown

Key Concepts:

  • Weighted Decision Matrix: Engineering design fundamentals
  • The Path Not Taken: “Software Systems Architecture” Ch. 7

Difficulty: Intermediate Time estimate: 1-2 weeks Prerequisites: Understanding of basic system design.

Real World Outcome

An ADR that looks like a technical review, silencing future “Why didn’t they just use X?” questions.

Example Output:

# 7. Selection of Message Broker

## Comparison Matrix

| Criteria | RabbitMQ | Kafka | Redis Pub/Sub |
|----------|----------|-------|---------------|
| Durability | High | Very High | Low |
| Throughput | Medium | High | Extreme |
| Complexity | Medium | High | Low |
| **Winner** | | **X** | |

## Project 4: The ADR CLI (Automating the Workflow)



- **File**: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

- **Main Programming Language**: Python

- **Alternative Programming Languages**: Bash, Go, Rust

- **Coolness Level**: Level 3: Genuinely Clever

- **Business Potential**: 2. The "Micro-SaaS / Pro Tool"

- **Difficulty**: Level 2: Intermediate

- **Knowledge Area**: CLI Tools / File I/O

- **Software or Tool**: Python `click` or `typer`

- **Main Book**: "The Pragmatic Programmer" by Hunt & Thomas



**What you'll build**: A CLI tool named `adr-tool` that automates the lifecycle of an ADR. It should support `init`, `new`, `list`, and `supersede`.



**Why it teaches ADRs**: Friction is the enemy of documentation. By building a tool to automate the creation and numbering of ADRs, you learn how to enforce a consistent workflow across a team.



**Core challenges you'll face**:

- **Handling Numbering** → maps to *ensuring sequential IDs without collisions*

- **Template Injection** → maps to *using Jinja2 or f-strings for dynamic content*

- **Superseding Logic** → maps to *updating the status of one file while creating another*



**Key Concepts**:

- **Automation of Repetitive Tasks**: "The Pragmatic Programmer" Topic 29

- **CLI Design**: "Click" library documentation (Python)



**Difficulty**: Intermediate

**Time estimate**: 1 week

**Prerequisites**: Project 1 completion, basic Python.



---



## Real World Outcome



A command-line tool that makes writing ADRs as easy as committing code.



**Example Output:**

```bash

$ adr-tool init docs/arch/adr

Initialized ADR repository in docs/arch/adr



$ adr-tool new "Use Redis for Session Cache"

Created ADR 0008: docs/arch/adr/0008-use-redis-for-session-cache.md



$ adr-tool supersede 0003 "Migrate from Postgres to DynamoDB"

ADR 0003 status updated to SUPERSEDED.

Created ADR 0009: docs/arch/adr/0009-migrate-from-postgres-to-dynamodb.md

The Core Question You’re Answering

“How do we make the ‘right thing’ the ‘easiest thing’?”

If creating an ADR takes 10 minutes of manual formatting, developers won’t do it. If it takes 1 command, they might. Good architecture requires good ergonomics.

Project 5: ADR Visualizer (The Decision Graph)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Python / JavaScript

  • Alternative Programming Languages: Go (with Mermaid.js)

  • Coolness Level: Level 5: Pure Magic (Super Cool)

  • Business Potential: 4. The “Open Core” Infrastructure

  • Difficulty: Level 3: Advanced

  • Knowledge Area: Graph Theory / Visualization

  • Software or Tool: Graphviz or Mermaid.js

  • Main Book: “Fundamentals of Software Architecture” by Richards & Ford

What you’ll build: A tool that parses your directory of ADRs and generates a visual dependency graph showing how decisions relate to each other (which ones superseded others, which ones depend on previous choices).

Why it teaches ADRs: You’ll see the “Architecture Lineage.” This project forces you to understand the relationship between decisions and how the system’s design evolved over time.

Core challenges you’ll face:

  • Parsing Markdown Metadata → maps to regex or front-matter parsing

  • Building a Directed Acyclic Graph (DAG) → maps to representing the flow of time and logic

  • Auto-generating Mermaid/Dot code → maps to translating data structures to visual syntax

Key Concepts:

  • Architectural Lineage: “Fundamentals of Software Architecture” Ch. 19

  • Graph Visualization: Mermaid.js documentation

Difficulty: Advanced

Time estimate: 2 weeks

Prerequisites: Project 4 completion.

Real World Outcome

A beautiful SVG or HTML page showing the “Family Tree” of your architecture.

Example Output:


graph TD

    ADR1[ADR 1: Init] --> ADR2[ADR 2: Python]

    ADR2 --> ADR4[ADR 4: Monolith]

    ADR4 -.->|Superseded by| ADR12[ADR 12: Microservices]

    ADR2 --> ADR3[ADR 3: Postgres]

Project 6: The Integrity Linter (Enforcing Decision Quality)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Python

  • Alternative Programming Languages: Rust, JavaScript

  • Coolness Level: Level 2: Practical but Forgettable

  • Business Potential: 3. The “Service & Support” Model

  • Difficulty: Level 3: Advanced

  • Knowledge Area: Static Analysis / NLP

  • Software or Tool: pylint style logic or LLM APIs

  • Main Book: “Code Complete” by Steve McConnell

What you’ll build: An “ADR Linter” that checks for quality issues: missing sections, empty “Consequences,” or the use of forbidden vague words like “better,” “easier,” or “faster” without data.

Why it teaches ADRs: You learn what makes a bad ADR. By codifying quality rules, you internalize the principles of high-quality architectural communication.

Core challenges you’ll face:

  • Structure Validation → maps to ensuring all Nygard headers exist

  • Sentiment/Keyword Analysis → maps to detecting vague language

  • CI/CD Integration → maps to failing a PR if the ADR is low quality

Key Concepts:

  • Documentation Quality: “Code Complete” Ch. 32

  • Pre-commit Hooks: Git hooks documentation

Difficulty: Advanced

Time estimate: 1-2 weeks

Prerequisites: Project 4.

Real World Outcome

A CI check that tells your team: “ADR 0014 is invalid: ‘Consequences’ section must have at least 2 bullet points.”

Example Output:

```bash

$ adr-lint docs/adr/0014-use-kafka.md

[ERROR] Missing ‘Alternatives’ section.

Project 7: The ADR Review Bot (GitHub Action)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: TypeScript / JavaScript

  • Alternative Programming Languages: Python, Go

  • Coolness Level: Level 3: Genuinely Clever

  • Business Potential: 3. The “Service & Support” Model

  • Difficulty: Level 2: Intermediate

  • Knowledge Area: DevOps / GitHub APIs

  • Software or Tool: GitHub Actions / Probot

  • Main Book: “The Phoenix Project” by Gene Kim

What you’ll build: A GitHub Action that triggers whenever a file in docs/adr/ is modified. It automatically tags the “Architectural Review Board” (a specific team) and posts a summary of the decision to a Slack/Discord channel.

Why it teaches ADRs: Architecture decisions shouldn’t happen in a vacuum. This project teaches you how to integrate architectural governance into the developer’s existing workflow (the Pull Request).

Core challenges you’ll face:

  • Parsing PR Diffs → maps to identifying which ADR is being changed

  • Team Tagging Logic → maps to mapping file paths to ownership

  • Webhooks/API Integration → maps to connecting GitHub to communication tools

Key Concepts:

  • Continuous Integration of Architecture: “Fundamentals of Software Architecture” Ch. 20

  • Automated Governance: “The Phoenix Project”

Difficulty: Intermediate

Time estimate: 1 week

Prerequisites: Project 4.

Real World Outcome

Every time a developer proposes a new architecture change, the right people are notified automatically with a summary of the trade-offs.

Example Output:

[GitHub Action] New ADR Proposed: #0015

Title: Use gRPC for Internal Services

Author: @douglas

Impact: High (One-Way Door)

Summary: Moving away from REST to reduce latency.

Reviewers: @architecture-team

Project 8: Decision Debt Analytics (The ADR Dashboard)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Python / SQL

  • Alternative Programming Languages: R, Go

  • Coolness Level: Level 4: Hardcore Tech Flex

  • Business Potential: 4. The “Open Core” Infrastructure

  • Difficulty: Level 4: Expert

  • Knowledge Area: Data Analysis / Business Intelligence

  • Software or Tool: Pandas / Streamlit / SQLite

  • Main Book: “The Software Architect Elevator” by Gregor Hohpe

What you’ll build: A dashboard that analyzes your ADR history to find “Decision Debt.” It calculates:

  1. Decision Density: How many decisions per 1,000 LOC?

  2. Superseding Velocity: How often do we change our minds?

  3. Ghost Decisions: Areas of the code with 0 ADRs (potentially high risk).

Why it teaches ADRs: This moves you from documentation to “Decision Science.” You learn to treat architectural choices as a data set that reveals the health of the project.

Core challenges you’ll face:

  • Mining Git History → maps to associating ADRs with code commits

  • Calculating “Churn” → maps to identifying unstable architectural areas

  • Visualizing Metrics → maps to making complex data actionable for management

Key Concepts:

  • Architecture Metrics: “Fundamentals of Software Architecture” Ch. 6

  • Decision Churn: “The Software Architect Elevator” Ch. 18

Difficulty: Expert

Time estimate: 2-3 weeks

Prerequisites: Project 5 & 6.

Real World Outcome

A dashboard showing your CTO exactly where the “Architectural Hotspots” are in the codebase.

Example Output:

  • Average Decision Age: 142 days

  • Most Volatile Component: Auth Service (4 superseded ADRs in 3 months)

  • Documented Coverage: 65% of modules have associated ADRs.

  • Top Constraint: “Speed to Market” (Cited in 80% of ADRs).

Project 9: The ADR Storyteller (Generative History)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Python (LLM)

  • Alternative Programming Languages: Node.js

  • Coolness Level: Level 5: Pure Magic (Super Cool)

  • Business Potential: 5. The “Industry Disruptor”

  • Difficulty: Level 4: Expert

  • Knowledge Area: AI / Large Language Models

  • Software or Tool: OpenAI API / LangChain

  • Main Book: “Design It!” by Michael Keeling

What you’ll build: A tool that uses an LLM to read all your ADRs and generate a “Narrative History of the System.” It explains the evolution of the architecture as if it were a story, highlighting the turning points and major pivots.

Why it teaches ADRs: To synthesize the history, you must understand the narrative arc of the architecture. This project forces you to see how individual decisions aggregate into a “Macro-Architecture.”

Core challenges you’ll face:

  • Context Window Management → maps to summarizing large sets of ADRs

  • Relationship Extraction → maps to identifying the ‘why’ behind the ‘pivot’

  • Fact Verification → maps to ensuring the AI doesn’t hallucinate decisions

Key Concepts:

  • The Architecture Narrative: “Design It!” Ch. 14

  • RAG (Retrieval-Augmented Generation): AI engineering basics

Difficulty: Expert

Time estimate: 2-4 weeks

Prerequisites: Project 5.

Real World Outcome

A “Design History” document that can be handed to any new hire, explaining the 2-year journey of the system in 10 minutes.

Example Output:

“The system began as a Python monolith (ADR 2, 4) focused on speed. By month 6, scaling issues with the database led to the introduction of Kafka (ADR 7) and a pivot to microservices (ADR 12). The most significant conflict occurred in ADR 15, where the team chose gRPC, effectively standardizing our internal communication for the next year…”

Project 10: The MCDA ADR (Scientific Comparison)

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Markdown / Python (for calculation)

  • Alternative Programming Languages: Excel / Google Sheets

  • Coolness Level: Level 3: Genuinely Clever

  • Business Potential: 1. The “Resume Gold”

  • Difficulty: Level 3: Advanced

  • Knowledge Area: Decision Theory / Mathematics

  • Software or Tool: Multi-Criteria Decision Analysis (MCDA)

  • Main Book: “Software Systems Architecture” by Rozanski & Woods

What you’ll build: An ADR that uses a formal MCDA (Multi-Criteria Decision Analysis) framework. You’ll define weights for criteria (Cost: 0.2, Performance: 0.5, etc.) and score options to remove emotional bias from a high-stakes decision.

Why it teaches ADRs: Sometimes “gut feeling” is wrong. This teaches you how to handle complex decisions where multiple valid criteria conflict. It’s the ultimate “Type 1” decision tool.

Core challenges you’ll face:

  • Defining Objective Weights → maps to aligning technical choices with business priorities

  • Scoring Normalization → maps to comparing apples to oranges (e.g., $ vs ms)

  • Sensitivity Analysis → maps to testing if changing a weight changes the winner

Key Concepts:

  • Formal Decision Models: “Software Systems Architecture” Ch. 7

  • MCDA (Multi-Criteria Decision Analysis): Operations research basics

Difficulty: Advanced

Time estimate: 1 week

Prerequisites: Project 3.

Project 11: The ADR Inconsistency Auditor

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Python

  • Alternative Programming Languages: Go

  • Coolness Level: Level 4: Hardcore Tech Flex

  • Business Potential: 3. The “Service & Support” Model

  • Difficulty: Level 4: Expert

  • Knowledge Area: Knowledge Graphs / Semantic Search

  • Software or Tool: Vector Embeddings (Sentence Transformers)

  • Main Book: “Building Microservices” by Sam Newman

What you’ll build: A tool that scans ADRs across different repositories in your organization and finds contradictions (e.g., Repo A decided to use Postgres for everything, but Repo B decided to use MongoDB for the same use case).

Why it teaches ADRs: In large organizations, architecture drifts apart. This project teaches you about “Global vs. Local” optimization and how to manage a unified architectural vision.

Core challenges you’ll face:

  • Semantic Mapping → maps to understanding that ‘DB’ and ‘Datastore’ are the same thing

  • Conflict Detection → maps to identifying when two decisions address the same problem

  • Reporting Hierarchy → maps to escalating inconsistencies to the right team

Key Concepts:

  • Microservices Governance: “Building Microservices” Ch. 11

  • Architectural Coherence: “The Software Architect Elevator” Ch. 12

Difficulty: Expert

Time estimate: 3-4 weeks

Prerequisites: Project 8 & 9.

Project 12: The Architecture Decision “Stock Exchange”

  • File: ARCHITECTURE_DECISION_RECORDS_MASTERY.md

  • Main Programming Language: Web (React/Node)

  • Alternative Programming Languages: Python / Streamlit

  • Coolness Level: Level 5: Pure Magic (Super Cool)

  • Business Potential: 5. The “Industry Disruptor”

  • Difficulty: Level 5: Master

  • Knowledge Area: Full Stack / Game Theory

  • Software or Tool: Custom Web App

  • Main Book: “Fundamentals of Software Architecture” by Richards & Ford

What you’ll build: A “Stock Exchange” for decisions. Team members “buy shares” in a decision (betting it will be successful). 12 months later, the decision is audited. If the “Consequences” were accurate, the “stock” goes up. If it failed, it goes down.

Why it teaches ADRs: This is the ultimate feedback loop. It forces you to be brutally honest in your ADRs because your “reputation” as an architect is tied to the accuracy of your predictions.

Core challenges you’ll face:

  • Defining “Success” Metrics → maps to closing the loop on architectural choices

  • Handling the Audit Cycle → maps to temporal data management

  • Gamification Mechanics → maps to incentivizing honest documentation

Key Concepts:

  • Architecture Feedback Loops: “Fundamentals of Software Architecture” Ch. 19

  • Prediction Markets: Behavioral economics

Difficulty: Master

Time estimate: 1 month+