The C4 + ADR + arc42 system

Overview

The two previous lessons resolved where to put the doc (in the repo, close to the code) and how to keep it synchronized (docs-as-code, validated in CI). This lesson resolves what to document and how those pieces assemble into a system. Because there's a silent mistake in how many people think about architecture documentation: they imagine it as one artifact —"the diagram" or "the document"— when in reality it's a system of complementary pieces, each designed to answer a distinct kind of question. The combo this lesson assembles is the one that has proven to survive: C4 (the diagrams by level that show the structure), the ADR (the decision record that keeps the why), and arc42 (the template that organizes all that and covers what neither C4 nor the ADR reach).

The central idea is that none of the three pieces is enough alone, and this lesson measures it. An impeccable C4 diagram shows you what pieces there are and how they connect, but doesn't tell you why they were decided that way —that's what the ADR is for—. A perfect collection of ADRs explains the why of each decision, but doesn't give you the map of the structure or the list of quality attributes —that's what C4 and arc42 are for—. And arc42, which is the template, gives you the skeleton —the places where each thing goes, including the ones C4 and the ADR don't cover: the quality attributes, the constraints, the risks— but it's filled with C4 and ADRs, it doesn't replace them. The three together answer what a new person or an auditor needs to know; each one alone leaves gaps. This lesson executes the coverage of each one and demonstrates why the complete system is more than the sum —and what arc42 specifically adds as the skeleton that holds them—.

Connection with the module. It's the lesson that assembles the system. Lessons 2 and 3 said where and how the doc lives; this one says what it's made of. With the module's analogy: if the doc that survives is the folder the previous owner left you, this lesson is about the tabs of that folder —one for the map (C4), one for the decisions (ADR), and the structure of the folder itself with its sections (arc42)—. Frontier, and it's the most important of this lesson: here we don't re-teach how to draw C4 (that was module 3 of this guide) or the mechanics of writing an ADR (that's the sister guide architecture-decisions). It's assumed you already know how to produce those pieces; this lesson teaches how to assemble them into a system that lasts and to see what gap each one fills —the criterion of complete documentation, not the manual of each tool—.

An analogy: the tabbed filing cabinet vs. the pile of papers

Think of how a homeowner organizes —or doesn't— all the important papers of their house, and two ways of doing it.

The pile of papers. The owner has all the house's documents, but in a single pile on the desk: the blueprint, the deeds, the appliance warranties, the notes about why the cistern was moved, the receipts, the manuals. All the information exists —nothing was lost— but finding something is a nightmare: to know why the cistern is where it is, you have to dig through the whole pile hoping to hit the right note. And worse: since there's no structure, it's impossible to know what's missing. Is the house's electrical capacity documented? The known risks, like the roof leaking in heavy storms? No one knows, because there's no designated place for those things where their absence would be noticed. The pile has a lot of information and no way to use it or to audit what it lacks.

The tabbed filing cabinet. Another owner uses a filing cabinet with labeled tabs, each for a kind of information: tab "blueprints" (how the house is built), tab "decisions" (why the cistern was moved, why the load-bearing walls are where they are), tab "attributes" (electrical capacity, thermal insulation, how much water it holds), tab "risks" (the roof leaks in storms, the wiring is old in the east wing). Now, finding something is direct: each question has its tab. And —this is the powerful part— the structure itself reveals what's missing: if the "risks" tab is empty, it will jump out that no one documented the risks, because there's a designated place waiting for them. The cabinet doesn't just store the information; it organizes it so it's findable and its absence is visible.

Here's this lesson's system: arc42 is the tabbed filing cabinet; C4 and the ADR are content that goes in specific tabs. The cabinet's "blueprints" tab is where C4 lives (the structure); the "decisions" tab is where the ADRs live (the why); and arc42 adds tabs that neither C4 nor the ADR bring —"quality attributes", "constraints", "risks"— that without a designated place would be like the pile: information that's missing and that no one notices is missing. The pile of papers is having C4 and ADRs loose with no skeleton to organize them and show the gaps. The tabbed filing cabinet is the complete system: each kind of knowledge in its place, findable, and with the absences visible. This lesson measures why you need the whole cabinet and not just some tabs.

Worked example: the coverage of each piece and of the combo

We're going to measure the central claim: no piece alone is enough. We take the questions a new person or an auditor asks a system's documentation —eight concrete questions about Mercado— and see which artifact answers each one. Then we measure what fraction of those questions each documentation "kit" covers when used alone, and what the combo covers.

The eight questions split into three families: the structure ones (what there is, how it connects) are answered by C4; the why ones (why it was decided this way) are answered by the ADR; and the quality, constraints and risks ones are answered by arc42 in its dedicated sections. Let's see the coverage:

# The documentation system: C4 + ADR + arc42 aren't three loose things, they're a
# SYSTEM. Each artifact answers a kind of question; together they cover what a
# new person or an auditor needs to know. arc42 is the SKELETON that organizes them.
# We map real questions to the artifact that answers them and measure the coverage.
QUESTIONS = [
    # (question, artifact that answers it)
    ("What does the system do and who uses it?",            "C4-Context"),
    ("What deployable pieces is it made of?",               "C4-Container"),
    ("How is a piece structured inside?",                   "C4-Component"),
    ("Why was the queue chosen instead of direct write?",   "ADR"),
    ("Why is payments a separate service?",                 "ADR"),
    ("What are the quality attributes and their targets?",  "arc42-quality"),
    ("What are the technical constraints of the system?",   "arc42-constraints"),
    ("What risks and technical debt do we know of?",        "arc42-risks"),
]

# What each documentation "kit" covers if used ALONE:
KITS = {
    "C4 only":      {"C4-Context", "C4-Container", "C4-Component"},
    "ADR only":     {"ADR"},
    "arc42 only":   {"arc42-quality", "arc42-constraints", "arc42-risks"},
    "C4+ADR+arc42": {"C4-Context", "C4-Container", "C4-Component", "ADR",
                     "arc42-quality", "arc42-constraints", "arc42-risks"},
}

total = len(QUESTIONS)
print(f"{'kit':<16}{'answers':>12}{'coverage':>12}")
print("-" * 40)
for kit, artifacts in KITS.items():
    answered = sum(1 for _, art in QUESTIONS if art in artifacts)
    print(f"{kit:<16}{answered:>9}/{total}{answered / total * 100:>10.0f}%")
print("-" * 40)
for kit in ("C4 only", "ADR only", "arc42 only"):
    gaps = [q for q, art in QUESTIONS if art not in KITS[kit]]
    print(f"\n{kit} leaves UNANSWERED ({len(gaps)}):")
    for q in gaps:
        print(f"  - {q}")

What to expect. Running the file, the output is exactly this:

kit                  answers    coverage
----------------------------------------
C4 only                 3/8        38%
ADR only                2/8        25%
arc42 only              3/8        38%
C4+ADR+arc42            8/8       100%
----------------------------------------

C4 only leaves UNANSWERED (5):
  - Why was the queue chosen instead of direct write?
  - Why is payments a separate service?
  - What are the quality attributes and their targets?
  - What are the technical constraints of the system?
  - What risks and technical debt do we know of?

ADR only leaves UNANSWERED (6):
  - What does the system do and who uses it?
  - What deployable pieces is it made of?
  - How is a piece structured inside?
  - What are the quality attributes and their targets?
  - What are the technical constraints of the system?
  - What risks and technical debt do we know of?

arc42 only leaves UNANSWERED (5):
  - What does the system do and who uses it?
  - What deployable pieces is it made of?
  - How is a piece structured inside?
  - Why was the queue chosen instead of direct write?
  - Why is payments a separate service?

Read the coverage table first, because it's the lesson's argument in four lines.

Each piece alone leaves most of the questions unanswered. C4 alone answers 3 of 8 (38%): it shows you the structure —what the system does, what pieces it's made of, how a piece is structured inside— and nothing else. Look at what it leaves unanswered: the two why questions (why the queue, why payments separate) and the three of quality, constraints and risks. A new dev with only C4 knows how Mercado is built, but not why it's built that way or what guarantees it must meet —and that why is exactly what prevents them from "simplifying" a decision without understanding its reason—. The ADR alone answers 2 of 8 (25%): it gives you the whys, but without the map of the structure or the quality attributes, a new dev has a bunch of loose decisions with no map to place them. And arc42 "alone" —understood as its quality, constraints and risks sections— answers 3 of 8 (38%) but leaves the structure and the why unanswered.

The combo answers all eight: 100%. And it's not coincidence or redundancy —notice the coverages don't overlap—: C4 covers the three of structure, the ADR the two of why, and arc42 the three of quality/constraints/risks. Each piece covers a distinct family of questions, and the three families together are what someone needs to really understand a system: what there is (C4), why it's this way (ADR), and what it must meet and what threatens it (arc42). Removing any of the three leaves a whole gap: without C4, no map; without the ADR, no reasons; without arc42's sections, no documented quality attributes or risks. That's why it's a system and not a pile: each piece has its role, and the value is in the combination.

And arc42's special role. Notice that arc42 appears in two forms in the example. As its own content, it covers what neither C4 nor the ADR bring —quality, constraints, risks—. But its most important role isn't in the coverage table: arc42 is the skeleton that gives a place to everything, including C4 and the ADRs. In the arc42 template, C4 lives in the context and building-block-view sections; the ADRs live in the architecture-decisions section; and the quality, constraints and risks questions each have their section. arc42 doesn't compete with C4 and the ADR —it organizes them—: it's the tabbed filing cabinet where C4 goes in one tab, the ADRs in another, and there are tabs for what would be missing. That's why the complete system is called "C4 + ADR + arc42": the first two are content, the third is the structure that holds them and shows the gaps.

As a diagram, the system looks like this:

arc42 = the skeleton (the tabbed filing cabinet)
┌─────────────────────────────────────────────────────────────┐
│ arc42                                                         │
│  ├─ Context and scope ......... [ here goes C4-Context ]      │
│  ├─ Building block view ....... [ here goes C4-Container ]    │
│  │                             [ and C4-Component ]           │
│  ├─ Architecture decisions .... [ here go the ADRs ]          │
│  ├─ Quality goals ............. [ arc42's own content ]       │
│  ├─ Constraints ............... [ arc42's own content ]       │
│  └─ Risks and technical debt .. [ arc42's own content ]       │
└─────────────────────────────────────────────────────────────┘
  C4 shows the WHAT. The ADR keeps the WHY.
  arc42 organizes both and adds what's missing (quality, constraints, risks).

Deep dive: why these three, and how they assemble

The experiment showed that the three pieces cover families of questions that don't overlap. It's worth understanding why these three in particular form the system that survives, and how they assemble without duplicating.

Let's start with what each does well and why it's irreplaceable. C4 documents the structure in zoom levels —Context, Container, Component, Code— and its strength is that it's navigable: you can start at the map of the world (Context) and go down to where you need, giving each audience the right level (this was taught thoroughly in module 3). But C4 is deliberately mute about the why: a diagram shows that payments is separated and that there's a queue, never why. That silence isn't a flaw —a diagram that tried to explain every why would be illegible—; it's the reason another piece is needed. The ADR documents the why of each significant decision —context, decision, consequences— and its strength is that the reasoning travels through time: the dev who, two years from now, wonders "why doesn't payments write directly to the catalog?" finds the answer in the ADR, and doesn't undo the decision out of ignorance (its mechanics are the sister guide architecture-decisions). But a collection of ADRs, alone, is a bunch of decisions with no map to place them. That's why C4 and the ADR need each other: C4 is the map, the ADR is the legend of why the map is that way.

Now, why is a third piece needed, arc42? Because there's critical knowledge that's neither structure nor a single decision. The quality attributes and their targets ("payments must process peaks of X without going down", derived in module 5) aren't a diagram or an ADR: they're transversal properties of the whole system. The constraints ("we must use the cloud provider we already have contracted", "comply with such regulation") condition everything but aren't a box in a diagram. The risks and known technical debt ("the in-memory session installation doesn't hold beyond two instances", "we know search needs to be rewritten") are knowledge that saves whoever arrives from tripping over what we already knew —but that's lost if it has no place—. arc42 provides that place: it's a template of twelve sections (context, constraints, building block view, runtime view, decisions, quality requirements, risks, glossary, among others) where each kind of knowledge has its slot. Its value isn't teaching how to draw or decide —C4 and the ADR do that—; its value is being the complete skeleton that guarantees no dimension is forgotten, because each dimension has a section waiting for it, and an empty section screams that something is missing.

From there comes the most important point about how they assemble: arc42 doesn't replace C4 or the ADR; it houses them. A common mistake is to think you have to choose between C4, ADR and arc42, as if they competed. They don't compete: C4 is the content of arc42's context and building-block-view sections; the ADRs are the content of arc42's decisions section; arc42's quality, constraints and risks sections are filled by hand. The complete system is arc42 as structure, with C4 and ADRs as part of its content, plus the own content of the sections they don't cover. Writing "architecture documentation" is filling that skeleton: not all sections for all systems (a small system doesn't need the twelve), but the ones that matter, with the right piece in each.

An honest nuance so as not to turn this into a template cult. arc42 —or any template— is a scaffold, not an end. The goal isn't "having the twelve sections filled"; it's that the questions people actually ask have an answer, and that the important dimensions aren't forgotten. A small team with a simple system may need only three or four sections (context, key decisions, risks) and leave the rest empty or nonexistent —and that's fine—. The sin isn't leaving sections empty; the sin is not having the skeleton and thus forgetting a whole dimension (documenting the structure and the why, but never the risks, because there was no place that screamed their absence). Use arc42 as the cabinet that reminds you which tabs you might need, not as a bureaucratic checklist to be filled completely. And remember the previous lessons: all this lives in the repo (docs-as-code) and you document the stable, not the volatile (the next lesson) —the skeleton doesn't change those rules, it organizes them—.

Common mistakes

Confusing "a diagram" with "the documentation" (C4 only). What happens: the team draws a nice C4 and considers it "the architecture documentation", with no ADRs or the quality and risks sections. A new dev understands the structure but not why it's that way, and "simplifies" a decision without knowing its reason —reintroducing the problem the decision avoided—. Why it happens: the diagram is the most visible and tangible part of the doc, so the part is confused with the whole. How to spot it: if your doc answers "what there is" and "how it connects" but not "why it was decided this way" or "what it must meet", you have only C4 —38% of the system—. How to fix it: add the ADRs (the why) and the arc42 sections (quality, constraints, risks); the diagram is a piece of the system, not the system.

Collecting ADRs with no map (ADR only). What happens: the team writes ADRs diligently —good— but doesn't maintain a C4 or a skeleton, so there are thirty documented decisions loose and no map to place them. A new dev reads ADRs without understanding the structure they modify, like reading a company's meeting minutes without the org chart. Why it happens: ADRs are easy to write one by one and give a sense of progress, but without the structure that contextualizes them they lose half their value. How to spot it: if you have ADRs but no one can point on a diagram to which part of the system each one touches, you're missing the map. How to fix it: maintain an up-to-date C4 (the map) and organize the ADRs within the skeleton (arc42), so each decision can be located in the structure it affects.

Treating arc42 as a bureaucratic checklist to be filled completely. What happens: the team adopts arc42 and feels it must fill the twelve sections, so it produces section after section of filler content —empty or volatile— to "complete the template", and ends up with a giant document no one reads (exactly what module 3's lesson 7 warned about). Why it happens: the scaffold is confused with the end, and "all sections filled" becomes the goal instead of "the important questions answered". How to spot it: if you're writing sections because the template has them and not because someone will read them, or if your architecture doc weighs 200 pages, you fell into the bureaucracy. How to fix it: use arc42 as a reminder of which dimensions you might need, and fill only the ones that matter for your system —leave empty or nonexistent the ones that don't apply—; the skeleton serves to not forget dimensions, not to force documenting them all.

Exercises

Exercise 1 — The question each piece doesn't answer. For each of these three questions about Mercado, say which piece of the system (C4, ADR, or an arc42 section) answers it, and why the other two can't: (a) "why is payments separated from the core?"; (b) "what deployable containers is Mercado made of?"; (c) "what happens if the payment provider goes down —what risk do we have there?".

See solution

(a) "Why is payments separated?" → answered by the ADR. C4 can't: a diagram shows that payments is separated (a box apart), never why —a diagram is mute about the reasoning—. arc42 can't either, in its quality/constraints/risks sections: those describe properties and threats, not the why of a single decision. Only the ADR captures context + decision + consequences, which is exactly the shape of "why this was decided".

(b) "What containers is it made of?" → answered by C4 (Container level). The ADR can't: ADRs record decisions, not the inventory of the structure —you could read all the ADRs and not have the complete map of pieces—. arc42 houses the C4-Container in its building-block-view section, but the content that answers the question is the C4 diagram. Only C4 gives the navigable map of the deployable pieces.

(c) "What risk is there if the payment provider goes down?" → answered by arc42's risks section. C4 can't: it shows there's a dependency with the provider, but doesn't evaluate the risk of it failing. The ADR could touch the topic if there was a decision about it, but the systematic record of "what risks and technical debt we know of" is exactly arc42's risks section —the designated place for that kind of knowledge, which without a skeleton would be forgotten—. Only that section guarantees the risk is documented and doesn't live only in the head of whoever intuits it.

The pattern: each family of questions has its piece, and the others can't fill in for it because they're designed for something else. That's why the system needs all three —removing any leaves a family of questions unanswered—.

Exercise 2 — Why the coverage doesn't overlap. In the example, C4 covers 3 questions, the ADR 2, arc42 3, and the combo exactly 8 —the sum with no overlap—. Explain why it's good that the coverages don't overlap, and what it would mean (what problem there would be) if two of the pieces answered the same questions.

See solution

It's good that they don't overlap because it means each piece has a distinct and irreplaceable role: C4 is the only one that answers the structure, the ADR the only one that answers the why, arc42 the only one that answers quality/constraints/risks. With no overlap, each piece adds coverage no other provides, so the system is efficient —three pieces, zero redundancy, 100% coverage— and removing any leaves an identifiable gap. It's the sign of a good system of complementary pieces: each one does something the others don't.

If two pieces answered the same questions —say both C4 and the ADRs documented the structure— there would be a double problem. First, redundancy: you'd be maintaining the same information in two places, which costs double the effort. Second, and worse, desync risk: when the structure changed, you'd have to update both places, and sooner or later one would fall behind the other —C4 would say one thing and the ADRs another—, and then no one would know which to believe (exactly the trust problem of lesson 2, now between two pieces of your own doc). Documenting the same thing twice violates the DRY principle (don't repeat yourself) applied to doc: each fact should have one place where it lives, so there's one source of truth to maintain. That's why the good design of the doc system splits the questions without overlap: each kind of knowledge has exactly one responsible piece, and that piece is the source of truth for that knowledge.

Exercise 3 — Adapting the skeleton to a small system. A team of three maintains a small, simple internal service. Their lead reads about arc42 and says: "we have to document arc42's twelve sections to do it right". Another responds: "no, arc42 is pure overhead, let's just do a README". Using the idea of the skeleton as scaffold (not as checklist), explain why both are wrong and what you'd do.

See solution

The first is wrong to treat arc42 as a checklist to be filled completely: for a small, simple service, filling the twelve sections would produce a giant document of pure filler that no one would read —it falls into the mistake of the 500-page document—. arc42 is a scaffold that reminds you which dimensions you might need, not an obligation to document them all; "doing it right" isn't having the twelve sections, it's that the important questions have an answer.

The second is wrong to discard the skeleton entirely and keep only a README: with no skeleton, it's easy to forget a whole dimension —for example, never documenting why the key decisions were made (no ADRs) or the known risks, because there's no place that screams their absence—. The skeleton's value isn't the bureaucracy; it's that the absences are visible. A README alone answers "how do I run it and what does it do", but not the why or the risks.

What I'd do: use arc42 as a guide of what to consider, and fill only the sections that matter for this small system —probably four: a brief context (what it does and what it talks to, a C4-Context or even just prose), the key decisions (two or three ADRs for the why of the important stuff), an onboarding README (how to run it), and a risks/known-debt section—. The other eight arc42 sections (detailed runtime view, extensive glossary, elaborate quality scenarios) are left out because the system doesn't need them. That gets the best of both: the lightness the second asked for (not a giant document) and the guarantee of not forgetting dimensions that the first's skeleton gave. The skeleton adapts to the size of the system; it's neither ignored nor filled completely out of obligation. The rule: document what someone is going to read and what it would hurt to forget, and use the skeleton only to not forget —not to fill—.

Summary and next step

In this lesson you assembled architecture documentation as a system, not as a loose artifact: C4 (the structure, the what), the ADR (the decisions, the why), and arc42 (the skeleton that organizes them and adds quality, constraints and risks). You saw, with the tabbed filing cabinet vs. the pile of papers, that arc42 doesn't compete with C4 and the ADR but houses them —each kind of knowledge in its tab, and the absences visible—. And you measured it: each piece alone answers between 25% and 38% of the questions a new dev or an auditor asks, with coverages that don't overlap, while the combo answers 100% —because each piece covers a distinct family (structure, why, quality/risks) and the three together are what someone needs—. You learned that arc42 is a scaffold that adapts to the size of the system, not a checklist to be filled completely, and that its value is making the gaps visible, not forcing you to document everything.

Before moving on you should be able to: say which family of questions each piece answers (C4 the what, ADR the why, arc42 the quality/constraints/risks); explain why arc42 houses C4 and the ADR instead of competing with them; and adapt the skeleton to a small system without filling it completely or discarding it.

Lesson 5 answers the question this system leaves open: you now know what pieces make up the doc and where they go, but what information do you put inside each piece and which do you leave out? The answer is the rule that saves the doc from oblivion: document the stable, not the volatile. You're going to execute the ROI of documenting different things —the boundaries and the decisions (stable) against the endpoint lists and the signatures (volatile)— and discover that the variable that decides whether documenting something is worth it isn't its importance, but its volatility: the volatile costs more to maintain than it yields, and becomes obsolete before it's read. This lesson's system only survives if you fill it with the stable; the next teaches you to distinguish it.

Resources

• arc42.org — the twelve-section template (Gernot Starke and Peter Hruschka) that is this lesson's skeleton. The official documentation explains what goes in each section and how C4 and the ADRs fit inside. In English and German.
• Simon Brown — The C4 model (c4model.com) — C4 as the levels of the system's structure. In this guide it was taught how to draw it in module 3; here it's the piece that answers the what. In English.
• Michael Nygard — "Documenting Architecture Decisions" and adr.github.io — the ADR as the piece that answers the why. Its mechanics are the sister guide architecture-decisions; here it's a component of the system. In English.
• Gernot Starke, Effective Software Architectures and the material of arc42 by example — real examples of filled arc42, useful for seeing how C4 and the ADRs are housed within the skeleton and how it adapts to the size of the system. In English.
• Stefan Zörner, Softwarearchitekturen dokumentieren und kommunizieren — an in-depth treatment of how to combine C4, ADR and arc42 into a coherent documentation system (a classic reference in the arc42 world). In German, with transversal ideas.