Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 50 ยท Software Design

Architecture Decisions and Documentation

Learn how to document architecture: decision records (ADRs), the C4 model's four levels, quality attribute scenarios and how to record technical debt trade-offs.

Architecture is mostly decisions, and decisions are easy to forget. Two years after a team picks a message queue over direct calls, the people who chose it have left, the reasons are lost, and a newcomer either keeps it out of fear or rips it out in ignorance. Both can be expensive mistakes. Good architecture documentation does not try to describe everything; it keeps the important decisions and their reasons where the next person can find them, and gives a few clear pictures of the structure.

This lesson covers three lightweight tools: architecture decision records to capture why, the C4 model to draw what, and quality attribute scenarios to state how good the system must be. All of them are text and diagrams, so the real artifacts appear in read-only blocks. Two small JavaScript stand-ins at the end show how such records can be kept as data and checked automatically; they are teaching aids, not real documentation tools.

Architecture decision records

An architecture decision record (ADR) is a short document about one significant decision. It is written when the decision is made, kept in the repository next to the code (commonly in a docs/adr folder), and never rewritten afterward. If the decision changes, you write a new ADR that supersedes the old one, so history stays visible.

A common format has five parts:

TEXT
# ADR 007: Use PostgreSQL as the primary database

Status: Accepted (2026-02-14)

## Context
Orders, customers and payments need transactions and relational
queries. The team knows SQL well. We expect 50 GB of data in year one.

## Decision
We will use PostgreSQL, managed by our cloud provider.

## Consequences
+ Strong transactions and mature tooling.
+ Team can be productive immediately.
- Horizontal write scaling is harder than with some alternatives.
- We are tied to the provider's backup and upgrade schedule.

## Alternatives considered
- MongoDB: flexible schema, but our data is highly relational.
- SQLite: too limited for concurrent writers at our scale.

What makes an ADR good:

  • It records the context. The same decision can be right in one situation and wrong in another; the context is what lets a reader judge whether it still applies.
  • It lists consequences honestly, including the bad ones. An ADR with no downsides is advertising.
  • It names the alternatives and why they lost. This stops the same debate from restarting every six months.
  • It has a status: proposed, accepted, deprecated or superseded by ADR n.
  • It is short. One page, readable in two minutes. Write one ADR per decision, not one giant document.

Not every choice deserves an ADR. A good filter: does it affect structure, a key quality, dependencies or interfaces, and would it be costly to reverse? Picking the name of a variable does not qualify; picking a database does.

The C4 model

Architecture diagrams often fail because they mix levels: one box is a whole system, the next is a single class. The C4 model, created by Simon Brown, solves this by giving four levels of zoom, like a map with country, city, street and building views. Each diagram shows only one level.

Four levels of zoom

  1. Context
Your system as one box, with its users and other systems.
  1. Containers
The deployable parts: apps, databases, queues.
  1. Components
Major building blocks inside one container.
  1. Code
Classes and functions, usually generated.

Most teams only draw levels 1 and 2, and level 3 for the tricky parts.

1 / 2

In C4 vocabulary a container is a separately running thing, such as a web app, a mobile app, a database or a message broker. It is not a Docker container, although it may run in one. A system context diagram (level 1) might look like this in Mermaid:

flowchart TB
    U["Customer<br/>buys books"] -->|"browses and orders"| S["Online Bookshop<br/>software system"]
    S -->|"charges cards"| P["Payment Provider<br/>external system"]
    S -->|"sends receipts"| M["Email Service<br/>external system"]

Level 1: the bookshop as a single box, with the people and external systems it talks to.

Zooming into the bookshop gives level 2:

flowchart TB
    U["Customer"] -->|"HTTPS"| W["Web App<br/>container"]
    W -->|"JSON over HTTPS"| A["API<br/>container"]
    A -->|"SQL"| D[("Database<br/>container")]
    A -->|"publishes events"| Q["Message Queue<br/>container"]
    Q --> N["Notification Worker<br/>container"]
    N -->|"sends"| E["Email Service<br/>external"]

Level 2: the deployable parts and how they talk, with the technology on each arrow.

Rules of thumb for C4 diagrams: give every box a name, a type and a one-line responsibility; label every arrow with what it carries and how; include a title and a legend; and keep them small enough to read. The C4 diagrams are different from UML in that they are deliberately informal and few; see the UML overview for the formal notations and for deployment views.

Quality attribute scenarios

"The system must be fast and secure" is not a requirement anyone can check. A quality attribute scenario makes it concrete by describing a situation and a measurable response. It has six parts:

Part Question Example
Source Who or what causes it? A customer
Stimulus What happens? Submits an order during a sale
Environment Under what conditions? Normal operation, 5,000 users online
Artifact What part of the system? The checkout API
Response What should the system do? Accepts and confirms the order
Response measure How do we judge it? 95% of requests finish in under 800 ms

Scenarios turn vague qualities from software qualities and non-functional requirements into tests an architecture can be evaluated against. They also expose conflicts early: a scenario demanding a 200 ms response and another demanding strong auditing on every request will pull the design in different directions, and you want to find that in a meeting, not in production.

Architects use sets of scenarios to compare candidate designs. For each scenario, ask: does this design meet the measure, and what does it cost to do so? The scenarios that are hard to satisfy are the architecturally significant ones, and they deserve ADRs.

Technical debt as a recorded trade-off

Sometimes the right decision is a shortcut: ship a simple but limited solution now to meet a deadline. That creates technical debt, which is acceptable if it is a conscious, recorded choice and not an accident. The ADR is the place to record it: write the shortcut as a consequence ("we accept synchronous email sending for now; this will block checkout if the provider is slow"), state the trigger for paying it back ("revisit when daily orders exceed 2,000"), and give the ADR a status that flags it. Debt you have written down can be scheduled; debt nobody knows about simply grows. The next lesson on API design and the later one on technical debt and refactoring go deeper.

Documentation that stays alive

A few habits keep architecture documents useful:

  • Store them in version control with the code, so changes to code and docs can be reviewed together.
  • Prefer a small number of well-maintained diagrams over many stale ones; each diagram should have a clear audience.
  • Generate what can be generated (dependency graphs, API specs) and hand-write only the why.
  • Review ADRs like code. A pull request that changes the architecture should add or update one.

Stand-in: ADRs as data

Plain Markdown is the real format, but because ADRs follow a fixed shape you can treat them as data and check them. The stand-in below holds a few ADRs as objects, finds problems (missing alternatives, no negative consequences, superseded decisions that point nowhere) and prints a status list.

JS Check a set of decision records

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The checker only tests the shape of the records. It cannot tell whether a decision was wise; that still takes people reading and discussing it.

Stand-in: judging a design against scenarios

A scenario has a measurable response, so you can compare a measured or estimated value with the target. This stand-in uses made-up estimates for one candidate design and reports which scenarios pass. In real work the estimates would come from prototypes, load tests or experience.

JS Evaluate a design against quality scenarios

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The failing rows are exactly where an architect should look for design changes or for an honest ADR about accepting the gap.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is an ADR never edited to change its decision?

    ADRs are a log of decisions. Superseding rather than rewriting keeps the record of what was decided and why at each point.
  2. 2. In the C4 model, what is a container?

    A C4 container is a deployable or runnable unit. It may run in a Docker container, but the term is not limited to that.
  3. 3. Which part of a quality attribute scenario makes it testable?

    A measurable target, such as 95% of requests under 800 ms, lets you judge a design against the scenario.
  4. 4. Why should an ADR list negative consequences?

    Honest trade-offs let future readers judge whether the context has changed enough to reconsider the decision.
  5. 5. How should deliberate technical debt be handled in architecture documentation?

    Known, written-down debt can be scheduled and repaid; unrecorded debt is forgotten until it hurts.

Summary

  • Architecture documentation should capture the important decisions and their reasons, not every detail.
  • An ADR records one decision: status, context, decision, consequences and alternatives; superseded, never rewritten.
  • The C4 model shows a system at four zoom levels: context, containers, components, code. One level per diagram.
  • Quality attribute scenarios (source, stimulus, environment, artifact, response, measure) turn vague qualities into checkable targets.
  • Record deliberate shortcuts as technical debt with a trigger to revisit.
  • Keep documents in version control and review them like code.

Next: API and Interface Design.