Diagrams, design docs and decision records

A design nobody else can read cannot be reviewed. In a design round, a diagram the interviewer cannot follow is a design they cannot assess; at work, a decision nobody wrote down gets argued again every time someone new joins. Three artefacts carry most of the weight: a diagram of the structure, a sequence diagram of the one request that matters most, and a record of each decision and why it was taken.

Boxes, arrows and labels

The C4 model prescribes no notation, but the advice on its notation page makes a good checklist for any boxes-and-arrows diagram, whatever tool draws it:

• Every box says what it is. A name, the kind of thing it is (a person, an outside system, an application, a data store), a short line about its responsibility and, for applications and stores, the technology.
• Data stores look different from services. Shapes are your choice, and C4 asks only that the key explain the ones that carry meaning. This track draws a cylinder for a database and a queue shape for a queue, so a reader sees at a glance where data rests.
• Every arrow points one way and says what it does. “Reads and writes orders” says something; “uses” says nothing. Between applications and stores, add the protocol: “JSON over HTTPS”, “SQL over TLS”.
• A title and a key. Say what the diagram shows and at which level of detail, and explain any shape, line style or colour that carries meaning. Spell out abbreviations or put them in the key.
• Colour is optional. If it means something, use it the same way everywhere and never as the only signal: some readers do not see colours apart, and printouts are often black and white.

Levels of detail: context, container, component

The C4 model describes a system at four levels of zoom, and each answers a different question:

1. System context: your system as one box, with the people who use it and the outside systems it talks to. It is the picture you can show anyone, technical or not.
2. Container: inside the system boundary, the separately running applications and data stores, their technology and how they talk to each other. “Container” here has nothing to do with Docker: it means a web app, a service, a database, a queue, a bucket.
3. Component: the parts inside one container.
4. Code: classes and functions, which are rarely worth drawing by hand.

A design round mostly needs the container level plus one sequence diagram. One difference from C4 is worth knowing: C4 keeps load balancers, replicas and failover out of container diagrams and puts them in a separate deployment diagram, because they differ from one environment to the next. In a round you usually draw them on the same diagram, which is fine as long as each box is labelled for what it is. Here is a container diagram of an online shop’s checkout:

Try the one-minute test on it. Who uses it? A shopper. What runs? A web app, an API, a background worker. Where does data rest? An orders database and a queue. What is outside the team’s control? The payment and email providers. What crosses the network, and how? Every arrow says. A reviewer who can answer those five questions in a minute can spend the rest of the review on whether the design is right.

One request as a sequence diagram

A container diagram shows what exists. A sequence diagram shows what happens, in order, for one request: who calls whom, what is stored when, and what the caller hears back. C4 calls diagrams of behaviour “dynamic diagrams” and allows them in this sequence style. Draw one for the request that matters most, usually the hot path or the one that moves money:

The order of the steps is the design. The order is saved as pending before the card is charged, so if the API crashes between steps 3 and 5 there is a record to reconcile with the payment provider instead of a charge nobody knows about. The same idempotency key, k7, travels with the order and the charge, so a retry after a timeout finds the existing order rather than charging twice; the APIs module of this track shows how idempotency keys work. A container diagram cannot say any of this, which is why the two diagrams go together.

Keep diagrams as text, next to the code

A diagram can be a short text file that a tool turns into an image. In the D2 language, for example, the sequence diagram above takes seven lines of messages, and the order in which messages are written is the order in which they are drawn. Diagrams kept as text sit in the repository next to the code, change in the same pull request as the design they describe, and show a reviewable difference when they change.

Spot the problems

Before reading on, look at this diagram and list what you would change. The first question of the quiz at the end of this lesson asks for the problems.

Architecture decision records

An architecture decision record (ADR) is a short text file that records one decision. Michael Nygard’s original format, from the blog post that made the idea popular, has five parts:

• Title: a number and a short phrase that names the decision.
• Status: proposed, accepted, deprecated, or superseded by a later record.
• Context: the forces at play, stated as facts: requirements, constraints, what the team knows.
• Decision: what the team will do, in full sentences (“We will …”).
• Consequences: everything that follows from the decision, the bad and the neutral as well as the good.

Records are numbered in order and numbers are never reused. A decision that is reversed is not edited away: its record stays, marked superseded, and a new record explains the new decision, so the history of the design survives. Each record is short, one or two pages at most. The MADR template, from the architecture decision records community, adds a list of the options that were considered with their pros and cons, which is often the most useful part for a later reader.

Here are two records for the link shortener of the earlier lessons, and a checker that looks for the parts above:

"""Check architecture decision records: a numbered title, the four sections of Michael Nygard's format,
a known status, and more than one consequence."""

import re
from pathlib import Path

REQUIRED = ["Status", "Context", "Decision", "Consequences"]
STATUSES = ("Proposed", "Accepted", "Deprecated", "Superseded")


def sections(text):
    """The lines under each '## ' heading, keyed by the heading."""
    found, current = {}, None
    for line in text.splitlines():
        if line.startswith("## "):
            current = line[3:].strip()
            found[current] = []
        elif current is not None and line.strip():
            found[current].append(line.strip())
    return found


def check(path):
    text = path.read_text(encoding="utf-8")
    title = re.match(r"# (\d+)\. (.+)", text)
    found = sections(text)
    status = (found.get("Status") or [""])[0]
    consequences = [line for line in found.get("Consequences", []) if line.startswith("- ")]

    problems = []
    if not title:
        problems.append('the title is not "# <number>. <decision>"')
    missing = [name for name in REQUIRED if name not in found]
    if missing:
        problems.append(f"missing {', '.join(missing)}")
    if status and not status.startswith(STATUSES):
        problems.append(f'status "{status}" is not one of {", ".join(STATUSES)}')
    if "Consequences" in found and len(consequences) < 2:
        problems.append("only one consequence: list the bad ones too")

    print(path.name)
    if title:
        print(f"  ADR {int(title.group(1))}: {title.group(2)}")
    print(f"  sections: {', '.join(found)}")
    print(f"  consequences: {len(consequences)}")
    print("  " + ("complete" if not problems else "needs work: " + "; ".join(problems)))


for name in sorted(p.name for p in Path(".").glob("[0-9][0-9][0-9][0-9]-*.md")):
    check(Path(name))

0001-record-clicks-in-a-log.md
  ADR 1: Record clicks in a durable log, not in the links database
  sections: Status, Context, Options considered, Decision, Consequences
  consequences: 5
  complete
0002-cache-redirects.md
  ADR 2: Cache redirects for one hour
  sections: Status, Context, Decision
  consequences: 0
  needs work: missing Consequences; status "Draft" is not one of Proposed, Accepted, Deprecated, Superseded

# 1. Record clicks in a durable log, not in the links database

## Status

Accepted

## Context

Every redirect of the link shortener is a click, and the owner of a link sees how many clicks it has had. The
requirements allow a count to be up to 60 seconds behind, and losing a few clicks when a server crashes is
acceptable; losing links is not. Redirects outnumber new links about 100 to 1, and 99% of them must be answered
within 100 ms. Writing a row to the links database for every click would put the busiest path of the system behind
the database's write capacity.

## Options considered

- Write each click to the links database during the redirect.
- Count clicks in the cache and copy the counts to the database every minute.
- Append each click to a durable, partitioned log, and count clicks in a separate consumer.

## Decision

We will append every click to a durable log from the redirect service, without making the redirect wait for it,
and run a consumer that adds clicks up and writes one count per link per minute to the links database.

## Consequences

- Redirects no longer wait for a database write, and the links database gets one write per active link per minute
  instead of one per click.
- Counts are behind by up to a minute in normal running; we alert when the lag passes 60 seconds.
- A click is lost if a redirect server dies before handing it to the log. We accept this.
- The log is a new component to run, monitor and pay for.
- If clicks ever become billable, this decision must be revisited, because billing needs every click counted.

# 2. Cache redirects for one hour

## Status

Draft

## Context

Most redirects are for a small share of the links.

## Decision

We will cache every redirect for one hour.

The first record passes, and its consequences are what make it honest: it says that clicks can be lost and that a new component has to be run, not only that redirects get faster. The second fails twice: “Draft” is not a status the team agreed on, and it has no consequences at all. The missing section hides a real problem. A redirect cached for an hour keeps working for up to an hour after its link expires or is deleted, while the requirements say an expired link answers 410 Gone. Writing the consequences down is how that conflict would have surfaced before the code did.

Design documents

At work, a design document gathers all of this for reviewers who were not in the room. This track uses an outline like the following; adapt it to your team’s habits:

1. Context and goals: the problem and the requirements, with numbers.
2. Non-goals: what the design leaves out on purpose.
3. The design: the container diagram, the sequence diagram of the critical request, the API and the data model.
4. Alternatives considered: the options that lost, and why.
5. Risks and open questions: what could go wrong, and how you will know it is working (the metrics and alerts).
6. Rollout: how the change reaches production, and how it is undone if it fails.

Decisions taken while writing it become decision records, and the document links to them, so that the document can age while the records stay true.

Key takeaways

• Label every box with what it is and every arrow with what it does, one way, with the protocol; draw data stores as stores, add a title and a key, and never let colour carry meaning alone.
• Use the C4 zoom levels: context for everyone, container for most design discussions, component and code rarely.
• Pair the container diagram with a sequence diagram of the request that matters most; the order of its steps is part of the design.
• Keep diagrams as text next to the code, so they change and are reviewed with it.
• Record each decision as a numbered ADR with status, context, decision and consequences, including the bad ones; supersede decisions instead of editing them away.