Your country

Tools that support it use your country for local currency, number formats, units and paper size. Your choice is saved only in this browser.

Type a name or a two-letter code. Use the up and down arrow keys to move through the countries, Enter to choose one and Escape to close.

System Design (High-Level Design)  Module 1 – Start here: how system design works

Diagrams, design docs and decision records

Draw context and container diagrams a reviewer can read in a minute, show one request as a sequence diagram, and record each decision as an ADR.

  • Beginner
  • 20 minutes
  • Examples run with Python 3.14.8, Pyodide 314.0.7, Node.js 24.21.0 and quickjs 0.32.0
  • By MySmartCoPilot
Free lesson, Pro answers: 20 minutes
Free: the whole lesson. With a pass: the model answers to its 2 interview questions.

What you will learn

  • Draw a system context and container diagram that a reviewer can read in one minute
  • Use a sequence diagram for one critical request flow
  • Fix the labels, shapes and levels of an unclear diagram
  • Write an architecture decision record with context, decision and consequences
  • Outline a design document that links to its decision records

Before you start

What you’ll learn · Before you start

What you will learn

  • Draw a system context and container diagram that a reviewer can read in one minute
  • Use a sequence diagram for one critical request flow
  • Fix the labels, shapes and levels of an unclear diagram
  • Write an architecture decision record with context, decision and consequences
  • Outline a design document that links to its decision records

Before you start

On this page

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: A diagram of one request over time. Each participant is a column, and the messages between them are arrows numbered in the order they happen, read from top to bottom. of the one request that matters most, and a record of each decision and why it was taken.

Every box says what it is, and every arrow what it does

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.

The arrows make the difference most often. Here are labels from the checkout diagrams of this lesson, against the ones that turn up when nobody follows the checklist:

On the arrow What a reader learns from it
uses Nothing: it fits any arrow on any diagram
data Neither what is sent nor which way it goes
reads and writes orders, SQL over TLS What the Checkout API does to the database, and how it talks to it
publishes order-paid, AMQP over TLS Which event leaves the API, where to, and over what

Each label on the right answers the reader’s next question before it is asked.

Checkpoint

Check: Boxes and arrows that say what they are

  1. Question 1 of 2 Which label is best for an arrow from the Checkout API to the orders database?

    Choose one answer.

    Show the answer: Question 1 of 2

    Answer: Reads and writes orders (SQL over TLS)

    A good label says what the arrow does, in the direction it points, and between containers which protocol it uses. "Uses", "data" and "connection" would fit any arrow on any diagram, so they tell the reader nothing.

  2. Question 2 of 2 Your diagram shows outside systems in grey and your own in blue. What else does the checklist ask for?

    Choose one answer.

    Show the answer: Question 2 of 2

    Answer: A key that explains the colours, and something besides colour that tells the two apart

    Colour is optional. If it means something, use it the same way everywhere, explain it in the key, and never let it be the only signal: here, a label such as "Not ours" or a boundary box tells the two apart in black and white.

Four levels of zoom, and the one a design round needs

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

  1. system context diagram: The widest view of the C4 model: the system as one box, with the people who use it and the outside systems it talks to, and no technology or inner structure.: 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.

Here is that first level for an online shop: the whole shop is one box, and only the people and systems around it are drawn.

System context diagram of a shop checkout: a shopper, the shop as one box, and the payment and email providers it calls.Shopper[person]Shop (ours)[software system]baskets, checkout and receiptsPayment provider[outside system]charges cardsEmail provider[outside system]delivers emailpays for a basketcharges the cardsends the receipt

System context diagram: the checkout as one box

Text description of the diagram

At the top is the shopper, a person, who pays for a basket in the shop.

In the middle is one box, "Shop (ours)", a software system that handles baskets, checkout and receipts. Nothing inside it is drawn at this level: no applications, databases or technologies.

Below it are two outside systems that the shop calls: a payment provider, which charges the card, and an email provider, which delivers the receipt.

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:

Container diagram of a shop checkout: a shopper, five parts of the shop with labelled arrows, and two outside providers.Shopper[person]Shop (ours)Not oursWeb app[single-page app in the browser]basket and checkout pagesCheckout API[stateless service]places and charges ordersOrders database[relational database]orders and their statusOrder events[message queue]Receipt worker[background service]emails receiptsPayment providercharges cardsEmail providerdelivers emailplaces an orderJSON over HTTPSreads and writes ordersSQL over TLSpublishes order-paidAMQP over TLSdelivers order-paidAMQP over TLSpays for a basketcharges the cardHTTPSsends the receiptHTTPS

Container diagram: the checkout of an online shop

Text description of the diagram

At the top is the shopper, a person, who pays for a basket in the web app.

The large box in the middle, labelled "Shop (ours)", holds the five parts of the system being designed, each with its kind in square brackets and one line about what it does: - the web app, a single-page app in the browser with the basket and checkout pages, which places an order with the Checkout API, sending JSON over HTTPS; - the Checkout API, a stateless service that places and charges orders; it reads and writes orders in the orders database using SQL over TLS, and publishes an order-paid event to the order events queue over AMQP over TLS; - the orders database, a relational database drawn as a cylinder, holding orders and their status; - order events, a message queue drawn as a horizontal cylinder, which delivers order-paid events to the receipt worker over AMQP over TLS; - the receipt worker, a background service that emails receipts.

At the bottom, a box labelled "Not ours" holds two outside systems: a payment provider, which the Checkout API calls over HTTPS to charge the card, and an email provider, which the receipt worker calls over HTTPS to send the receipt.

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.

Step through the same five questions on the diagram, one at a time, and check your own answers against each step:

Interactive · step by step The one-minute test on the checkout Step through the five questions a reviewer asks of a container diagram. Each step lights up the part of the checkout that answers one.
The one-minute test on the checkout, step 7 of 7. Showing Shopper, Payment provider, Web app, Checkout API, Orders database, Order events, Email provider, Receipt worker.pays for a basketplaces an order (HTTPS)charges the cardreads, writes orders (SQL)publishes order-paidorder-paid eventssends the receiptShopperPayment providernot oursWeb appin the browserCheckout APIstateless serviceOrders databaserelationalOrder eventsmessage queueEmail providernot oursReceipt workerbackground service

The drawing shows the whole scene; its 7 steps are listed below.

Every step as text
  1. The diagram as it arrives. The checkout's container diagram, as a reviewer first meets it. The test is to answer five questions about it within a minute, from the drawing alone.
  2. Who uses it?. A shopper, the one person on the diagram, drawn as a person, who pays for a basket in the web app.
  3. What runs?. Three applications run, a web app in the browser, a stateless Checkout API and a background worker that sends receipts. Each box names its kind and its job.
  4. Where does data rest?. Data rests in two stores, drawn as stores so that nobody has to guess, the orders database and the queue of order events.
  5. What is not ours?. Two outside systems, the payment provider and the email provider. The team calls them but does not run them, which is where its control ends.
  6. What crosses the network?. Every arrow says what it does, and the container diagram above adds how. The web app places an order with the API as JSON over HTTPS, and the API reads and writes orders using SQL over TLS.
  7. Five answers in a minute. All five answers came from the drawing, so the rest of the review can go to the question that matters, whether this design is right.

The context diagram above holds the same shop as a single box. The container diagram opened that box and kept everything around it, so a reader can move from one level to the next without meeting anything new outside.

Checkpoint

Check: The C4 levels of zoom

  1. Question 1 of 2 You must explain a new system to the finance team, who are not engineers. Which C4 diagram do you draw?

    Choose one answer.

    Show the answer: Question 1 of 2

    Answer: A system context diagram, with the system as one box among its users and the systems it talks to

    The context diagram leaves out technology and inner structure and shows the system in its surroundings, which is exactly what people outside the team need. The other levels are for technical readers.

  2. Question 2 of 2 In a design round, you draw the load balancer and the database replicas on your container diagram. Is that a mistake?

    Choose one answer.

    Show the answer: Question 2 of 2

    Answer: No, as long as each box is labelled for what it is, although C4 itself puts them in a separate deployment diagram

    C4 keeps load balancers, replicas and failover out of container diagrams, because they differ from one environment to the next, and shows them in a deployment diagram. 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.

A sequence diagram shows the order, and the order is the design

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: The operation a system performs most often, such as the redirect of a link shortener. A small cost on it is paid on every request, so it is one of the first places to look for a deep dive. More in “A step-by-step framework for a design round” or the one that moves money:

Sequence diagram of one checkout: seven numbered messages between the web app, Checkout API, orders database, payments and an events queue.Web appCheckout APIOrders databasePayment providerOrder events queue1. place order k72. save k7 as pending3. charge the card, key k74. approved5. mark k7 as paid6. publish order-paid7. 201 Created

Sequence diagram: one checkout request, in order

Text description of the diagram

Five participants stand in columns, from left to right: the web app, the Checkout API, the orders database, the payment provider and the order events queue. Time runs from top to bottom, and the messages are numbered in order.

  1. The web app asks the Checkout API to place order k7; k7 is the order's idempotency key.
  2. The Checkout API saves order k7 in the orders database with the status pending.
  3. The Checkout API asks the payment provider to charge the card, passing the same key, k7.
  4. The payment provider answers that the charge is approved.
  5. The Checkout API marks order k7 as paid in the orders database.
  6. The Checkout API publishes an order-paid event to the order events queue, which the receipt worker reads later.
  7. The Checkout API answers the web app with 201 Created.

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 A unique value the client sends with a request, so that a retry of the same request is recognised and not carried out a second time., 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.

Step through that crash. The middle messages of the checkout run as drawn, then the API fails at the worst moment:

Interactive · message by message A crash between the charge and "mark paid" Step through the middle of the checkout, then a crash at the worst moment, and see what saving the order first leaves behind.
A crash between the charge and "mark paid", step 9 of 9. Messages so far: Checkout API to Orders: save k7 as pending; Checkout API to Payments: charge the card, key k7; Payments to Checkout API: approved; Checkout API to Payments: status of k7?; Payments to Checkout API: k7 was charged; Checkout API to Orders: mark k7 as paid.Checkout APIand its jobsOrdersthe databasePaymentsthe providersave k7 as pendingcharge the card, key k7approvedstatus of k7?k7 was chargedmark k7 as paid

The drawing shows the whole scene; its 9 steps are listed below.

Every step as text
  1. Save first. Message 2 of the diagram. The order is saved as pending before any money moves.
  2. Charge with the key. Message 3. The charge carries the order's idempotency key, k7, so the provider can tell this charge from any other.
  3. Approved. Message 4. The provider approves, and the card has now been charged.
  4. The crash. The API crashes before message 5. The money has moved, and the database still says that order k7 is pending.
  5. A record survives. Because the order was saved first, the charge is not lost track of. A pending order k7 exists, written before the money moved.
  6. Reconcile. A reconciliation job of the checkout service looks at orders still pending after a few minutes, and asks the provider what happened to k7.
  7. The provider's record. The provider has a charge under k7, so the two records can be matched.
  8. Marked paid at last. The job marks k7 as paid, and the order carries on as if message 5 had never been lost.
  9. The other order. Had the API charged first and saved afterwards, the same crash would leave a charge with no order at all, money taken for something nobody can find. The order of the messages is the design.

The pending row written in step 2 is what turned a lost charge into a reconciled order. Swap steps 2 and 3, and the same crash leaves money taken with no order to match it.

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.

Checkpoint

Check: One request as a sequence diagram

  1. Question 1 of 2 In the checkout sequence diagram, why is the order saved as "pending" before the card is charged?

    Choose one answer.

    Show the answer: Question 1 of 2

    Answer: If the API crashes after the charge, there is still a record of the order to reconcile with the payment provider

    Writing the order first means no charge can happen without a record of what it was for. A crash between the charge and "mark paid" leaves a pending order that a reconciliation job can match with the provider's records.

  2. Question 2 of 2 A teammate adds a cache to the checkout and updates the D2 file of its diagram in the same pull request. What does that give the reviewer?

    Choose one answer.

    Show the answer: Question 2 of 2

    Answer: A difference in the diagram's text, beside the code change it describes, so both are reviewed together

    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.

An unclear diagram, fixed one rule at a time

Before reading on, look at this diagram and list what you would change. The checkpoint under it asks for the problems, and the figure after the checkpoint fixes them one rule at a time.

A small diagram for the checkpoint below: six plain boxes from Mobile app to Orders, joined by five arrows, some labelled.Mobile appLBAppCacheOrdersUserService.validate()usesdatacalls

For the checkpoint below: what would you change in this diagram?

Text description of the diagram

Six boxes, all plain rectangles of the same style, are labelled Mobile app, LB, App, Cache, Orders and UserService.validate().

The arrows are: - from Mobile app to LB, with no label; - from LB to App, labelled "uses"; - between App and Cache, a line with an arrowhead at both ends, labelled "data"; - from App to UserService.validate(), labelled "calls"; - from App to Orders, with no label.

Checkpoint

Check: Finding what makes a diagram unclear

  1. One question Look at the diagram in this section. Which of these are problems that make it hard to read?

    Choose every answer that is right.

    Show the answer: One question

    Answer:

    • The arrow between App and Cache points both ways, so you cannot tell who calls whom
    • Two arrows have no label at all
    • "LB" is an abbreviation that no key explains
    • The labels "uses" and "data" say nothing about what is sent or done
    • "Orders" is drawn like the other boxes, so you cannot tell whether it is a database, a service or a queue
    • It mixes levels of zoom, putting a method name next to whole applications and a load balancer

    Unlabelled and vague arrows, a two-way arrow, mixed zoom levels, a store that does not look like one and an unexplained abbreviation all make the reader guess. Colour and direction are left to you: one colour is fine, and top to bottom fits narrow screens better.

Six problems, and each one breaks a rule of the checklist at the start of this lesson. Step through the fixes, one rule at a time:

Interactive · step by step The unclear diagram, fixed one rule at a time Step through the fixes. Each step applies one rule of the checklist to the diagram above, and says what was wrong.
The unclear diagram, fixed one rule at a time, step 8 of 8. Showing Mobile app, Load balancer, Orders API, Cache, Orders database, User service.places orders, HTTPSforwards requestsreads product pageschecks the userreads, writes orders (SQL)Mobile apporders from a phoneLoad balancerwas: LBOrders APIwas: AppCacheproduct pagesOrders databasewas a plain boxUser servicewas a method name

The drawing shows the whole scene; its 8 steps are listed below.

Every step as text
  1. Boxes that say what they are. Every box now says what it is. LB is spelled out as a load balancer, and App is named for its job, the orders API.
  2. A store looks like a store. Orders is drawn as a database, so a reader sees at a glance where data rests.
  3. One level of zoom. UserService.validate() was a method, a piece of code inside one application. At the container level it becomes the user service it belongs to.
  4. The first two arrows. The arrow with no label and the one that said only "uses" now say what they carry, and the arrow from outside names its protocol.
  5. One way, saying what. The two-headed arrow labelled "data" becomes one arrow from the API to the cache that says what it reads, so who calls whom is no longer a guess.
  6. Calls, but for what?. "calls" becomes what the call is for: the API checks the user who placed the order.
  7. The last arrow. The arrow to Orders had no label at all. Now it says what it does and how.
  8. A title and a key. Last, a title says what the diagram shows and at which level, and a key explains the shapes. Every problem in the checkpoint above is gone.

No box was added and no part of the design changed: the same six parts, labelled and drawn by the rules, answer the one-minute test that the first version failed. Reviewing someone else’s diagram works in the same order: name the boxes, keep one level of zoom, then label every arrow, starting with the ones on the critical path.

A decision record keeps the reason after the people move on

An architecture decision record (ADR): A short, numbered text file that records one decision: its status, the context that forced it, the decision and its consequences. A reversed decision is marked superseded, never deleted. (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:

Two decision records and a checker

adr/adr_check.py

"""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))

Output

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

Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 adr_check.py

adr/0001-record-clicks-in-a-log.md

# 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.

adr/0002-cache-redirects.md

# 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.

Key idea

A decision record earns its place through its consequences: written down with the costs and risks, the second record would have shown its clash with the requirements before any code did.

Checkpoint

Check: Architecture decision records

  1. Question 1 of 2 Your team reverses a decision recorded in ADR 3. What should happen to ADR 3?

    Choose one answer.

    Show the answer: Question 1 of 2

    Answer: Keep it, mark it as superseded, and write a new ADR that explains the new decision and points back to it

    Records are history. The old one stays, marked superseded by the new one, so a reader can see what was decided, when it changed and why; numbers are never reused.

  2. Question 2 of 2 What belongs in the Consequences section of an ADR?

    Choose one answer.

    Show the answer: Question 2 of 2

    Answer: Everything that follows from the decision, including the costs and risks the team accepts

    A record that lists only benefits cannot be checked. The costs and risks are what a future reader needs most, because they are the reasons the decision may need to change. Rejected options belong in their own section.

A design document gathers it all for readers who were not there

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.

Most of the outline is the seven steps of a design round, written down. Here is where each section comes from:

Section of the document Where it comes from in a round
Context and goals The requirements, with the numbers of the estimates
Non-goals The non-goals said out loud in the requirements step
The design The API, the data model, the diagram and the sequence of the critical request
Alternatives considered The trade-offs behind each deep dive’s decision
Risks and open questions The wrap-up: bottlenecks, failure modes and what to measure
Rollout Nothing: a round ends before anything ships

A round that went well is most of a first draft; the rollout is the part only the work itself adds.

Checkpoint

Check: What a design document holds

  1. Question 1 of 2 In the design document outline, where do the options that lost go?

    Choose one answer.

    Show the answer: Question 1 of 2

    Answer: In "Alternatives considered", with the reason each one lost

    The outline gives the losing options a section of their own, "Alternatives considered", with the reason each one lost. Decisions taken while writing the document also become decision records.

  2. Question 2 of 2 Why does a design document link to decision records instead of holding every decision itself?
    Show the answer: Question 2 of 2

    Answer: The document ages as the system changes, while each record stays a true account of one decision

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

Markdown Editor Draft a decision record or a design document in Markdown, with a live preview.

Practise: number and name a new record

Write the two helpers a small tool needs to add the next record to a folder: the next number, which is never reused, and the file name. Their sample tests run here on the page, and the first hint is there when one fails:

Exercise · Easy · Python

Number and name a new decision record

Decision records live in a folder as NNNN-short-title.md: a four-digit number, then the title in lower case with hyphens. Numbers go up one at a time and are never reused, even when a record is deleted. Write two functions in adr_names.py that a small command-line tool could use to add the next record.

next_number(file_names) takes the names of the files in the folder, in any order, and returns the number for a new record: one more than the highest number in use. Only names that start with four digits and a hyphen and end in .md count; other files, such as README.md, are ignored. An empty folder starts at 1. A gap does not get filled:

next_number(["0001-use-postgres.md", "0003-cache-redirects.md", "README.md"])  # 4, not 2

file_name(number, title) returns the file name for a record: the number with four digits, a hyphen, then the words of the title (letters and digits only) in lower case, joined by single hyphens, and .md:

file_name(4, "Record clicks in a durable log")  # '0004-record-clicks-in-a-durable-log.md'
file_name(12, "Cache redirects: for 1 hour?")   # '0012-cache-redirects-for-1-hour.md'

The sample tests import both functions from adr_names.py and run in your browser.

Starter code · adr_names.py

def next_number(file_names):
    """The number for a new decision record: one more than the highest number in use, or 1."""
    # Replace this line with your code.
    return 0


def file_name(number, title):
    """'NNNN-words-of-the-title.md' for a record."""
    # Replace this line with your code.
    return ""
The sample tests · test_adr_names.py
from adr_names import file_name, next_number


def test_next_after_the_highest():
    """the next number is one more than the highest, in any order"""
    assert next_number(["0002-b.md", "0001-a.md"]) == 3
    assert next_number(["0010-j.md", "0009-i.md"]) == 11


def test_gaps_are_not_filled():
    """a number that was used once is never used again"""
    assert next_number(["0001-use-postgres.md", "0003-cache-redirects.md"]) == 4


def test_other_files_are_ignored():
    """only NNNN-....md names count, and an empty folder starts at 1"""
    assert next_number(["README.md", "template.md", "0001-a.md", "0005-draft.txt"]) == 2
    assert next_number([]) == 1
    assert next_number(["README.md"]) == 1


def test_file_name():
    """four digits, then the title in lower case with hyphens"""
    assert file_name(4, "Record clicks in a durable log") == "0004-record-clicks-in-a-durable-log.md"


def test_file_name_punctuation():
    """punctuation and extra spaces disappear"""
    assert file_name(12, "Cache redirects: for 1 hour?") == "0012-cache-redirects-for-1-hour.md"
    assert file_name(120, "  Use   UTC  everywhere ") == "0120-use-utc-everywhere.md"
A hint

For next_number, re.match(r"(\d{4})-.*\.md$", name) matches the names that count, and int(m.group(1)) is the number; the answer is max(...) + 1, or 1 when nothing matched. For file_name, re.findall(r"[a-z0-9]+", title.lower()) gives the words, "-".join(words) joins them, and f"{number:04d}" writes the number with four digits.

The sample tests run on this device, in your browser (Pyodide): nothing is sent to mysmartcopilot.com. The first run downloads Python (about 13.5 MB), which is kept for the next runs. A check in your browser is feedback for you, not proof that the code is right for every input.

Then the questions: labels, zoom levels, sequences, the unclear diagram, records and design documents, in the order your own answers call for. A wrong choice names the rule it breaks, so a miss is worth as much as a hit:

Practice that adapts to you

Practise this lesson

13 questions about 6 ideas of this lesson. Each answer is explained at once, and what you get right is kept in this browser.

  1. Question 1 of 13 What should every box on a container diagram say?

    Choose every answer that is right.

    Show the answer: Question 1 of 13

    Answer:

    • The kind of thing it is, such as an application or a data store
    • Its name
    • A short line about its responsibility
    • The technology, for applications and stores

    Every box says what it is: a name, the kind of thing it is, a short line about its responsibility and, for applications and stores, the technology.

  2. Question 2 of 13 An arrow from the receipt worker to the email provider is labelled "email". How would you improve it?

    Choose one answer.

    Show the answer: Question 2 of 13

    Answer: "Sends the receipt (HTTPS)": what the arrow does, in its direction, with the protocol

    Every arrow points one way and says what it does, with the protocol between applications and stores: the worker sends the receipt to the email provider over HTTPS.

  3. Question 3 of 13 In the C4 model, what is a container?

    Choose one answer.

    Show the answer: Question 3 of 13

    Answer: A separately running application or data store, such as a web app, a service, a database or a queue

    "Container" in C4 has nothing to do with Docker: it means something that must be running for the system to work, such as a web app, a service, a database, a queue or a bucket.

  4. Question 4 of 13 A new engineer will work inside the Checkout API and needs to know its main parts and how they fit together. Which level do you draw for them?

    Choose one answer.

    Show the answer: Question 4 of 13

    Answer: The component level of the Checkout API

    Each C4 level answers a different question. The component level opens one container, here the Checkout API, and shows its parts, which is what an engineer working inside it needs.

  5. Question 5 of 13 What does a sequence diagram show that a container diagram cannot?

    Choose one answer.

    Show the answer: Question 5 of 13

    Answer: What happens, in order, for one request

    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.

  6. Question 6 of 13 In the checkout, the API crashes after the provider approves the charge and before it marks k7 as paid. What is left behind?

    Choose one answer.

    Show the answer: Question 6 of 13

    Answer: A pending order k7 in the database and a charge under k7 at the provider, which a reconciliation job can match

    The order was saved as pending before the charge, so the crash leaves a pending k7 and a charge under k7 at the provider; matching the two marks the order paid.

  7. Question 7 of 13 What is wrong with an arrow that points both ways and is labelled "data"?

    Choose one answer.

    Show the answer: Question 7 of 13

    Answer: The reader cannot tell who calls whom, or what the data is

    An arrow that points both ways hides who starts the call, and "data" fits any arrow. One arrow, in the direction of the call, with what it does, says both.

  8. Question 8 of 13 The box "UserService.validate()" sits next to whole applications on a container diagram. What is the fix?

    Choose one answer.

    Show the answer: Question 8 of 13

    Answer: Draw the user service as one container, and leave its methods to a component or code view

    A diagram that mixes levels makes the reader switch zoom from box to box. At the container level, the method becomes the user service it belongs to.

  9. Question 9 of 13 Which parts belong to Michael Nygard's decision record format?

    Choose every answer that is right.

    Show the answer: Question 9 of 13

    Answer:

    • A numbered title that names the decision
    • The decision
    • The context
    • A status
    • The consequences

    Nygard's format has five parts: a numbered title, a status, the context, the decision and the consequences. MADR adds a list of the options that were considered.

  10. Question 10 of 13 The checker says ADR 2, "Cache redirects for one hour", needs work. Which problem in it matters most for the link shortener's users?

    Choose one answer.

    Show the answer: Question 10 of 13

    Answer: The missing consequences hide that an expired link would keep redirecting for up to an hour, while requirements say it answers 410 Gone

    The record fails twice: "Draft" is not an agreed status, and it has no consequences. The missing section hides a real conflict, because a redirect cached for an hour keeps working after its link expires or is deleted.

  11. Question 11 of 13 A folder holds ADR 1, ADR 2 and ADR 4; ADR 3 was deleted by mistake long ago. Which number does the next record get?

    Type a number.

    A hint

    Numbers are never reused, and they only go up.

    Show the answer: Question 11 of 13

    Answer: 5 (the record's number)

    Numbers go up one at a time and are never reused, so the next record is one more than the highest number in use: 4 + 1 = 5. Number 3 stays unused.

  12. Question 12 of 13 Put the sections of the lesson's design document outline in order.

    Give each item its position, from 1 (first).

    Show the answer: Question 12 of 13

    Answer:

    1. Context and goals
    2. Non-goals
    3. The design
    4. Alternatives considered
    5. Risks and open questions
    6. Rollout

    Context and goals, non-goals, the design, the alternatives considered, the risks and open questions, and the rollout: the same order as a design round, with a rollout that a round never reaches.

  13. Question 13 of 13 You turn a design round's answer into a design document. Which section has nothing to come from in the round?

    Choose one answer.

    Show the answer: Question 13 of 13

    Answer: Rollout, how the change reaches production and how it is undone

    Most of a design document has a step of the round behind it: requirements and estimates, the design itself, the deep dives' trade-offs, the wrap-up. Only the rollout is new, because a round stops before the design ships.

Interview questions

Warm-up (fresher to mid level): what is an architecture decision record, and what goes in one?

An architecture decision record, or ADR, is a short text file that records one decision about a system and the reason for it. Michael Nygard’s format has five parts: a numbered title that names the decision; a status, such as proposed, accepted, deprecated or superseded; the context, the facts and forces that made a decision necessary; the decision itself, in full sentences; and the consequences, the costs and risks as well as the gains. Records are numbered in order and kept beside the code. A decision that is reversed is never edited away: its record is marked superseded and a new one explains what changed, so the history survives. The consequences deserve the most care, because they tell a later reader when the decision stops being right.

That answer usually draws follow-ups. Here are three; choose the reply you would give, and each choice explains what it gets right or misses:

Checkpoint

Interview round: three follow-up questions

  1. Question 1 of 3 Follow-up: "When would you write a design document instead of only an ADR?"

    Choose one answer.

    Show the answer: Question 1 of 3

    Answer: When reviewers who were not in the room need the whole design, its diagrams, alternatives, risks and rollout, and not one decision

    A design document gathers the problem, the design, the alternatives, the risks and the rollout for reviewers who were not in the room; each decision inside it becomes a record that the document links to.

  2. Question 2 of 3 Follow-up: "A decision in ADR 4 turned out wrong a month later. What do you do with the record?"

    Choose one answer.

    Show the answer: Question 2 of 3

    Answer: Write ADR 9 (the next unused number) explaining what was learnt and the new decision, and mark ADR 4 superseded by it

    A reversed decision is not edited away: its record stays, marked superseded, and a new record explains the new decision, so the history of the design survives.

  3. Question 3 of 3 Follow-up: "In 45 minutes, which diagrams would you draw?"

    Choose one answer.

    Show the answer: Question 3 of 3

    Answer: A container diagram of the whole design, and one sequence diagram of the request that matters most

    A design round mostly needs the container level plus one sequence diagram: what exists, and what happens, in order, for the request that matters most.

Model answers open with any pass: ₹79 for 1 week ($2.99), one payment that never renews.

  1. Fresher to mid

    A teammate's diagram of a payment flow has five boxes, one of them called "Backend", and arrows labelled "calls" and "data". The design review starts in 15 minutes. What do you change first, and what do you ask the author?

    Model answer, Pro. Model answers open with any pass; prices are in the notice on this page. First step and follow-ups

  2. Mid to senior

    A year ago your team recorded ADR 7: "Cache redirects for one hour." A new requirement says an expired link must answer 410 Gone within a minute. How do you record the change, what goes in the new record, and what happens to ADR 7?

    Model answer, Pro. First step and follow-ups

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.
  • A design document gathers the requirements, the design, the alternatives, the risks and the rollout for readers who were not in the room, and links to the decision records taken along the way.

Terms in this lesson

architecture decision record (ADR)
A short, numbered text file that records one decision: its status, the context that forced it, the decision and its consequences. A reversed decision is marked superseded, never deleted.
sequence diagram
A diagram of one request over time. Each participant is a column, and the messages between them are arrows numbered in the order they happen, read from top to bottom.
system context diagram
The widest view of the C4 model: the system as one box, with the people who use it and the outside systems it talks to, and no technology or inner structure.

References

Related tools

Report a problem with this lesson

Quick answers and tool search

Type to search tools or to get a quick answer, for example 18% of 2500. Use the up and down arrow keys to move through the results, Enter to choose, and Escape to close.