1. Module introduction: communicate to be understood, not to archive

Overview

By the end of this lesson you'll understand the hardest truth to swallow for an engineer who takes pride in their technical rigor: an architecture decision no one understands doesn't exist. You can have the perfect design in your head —the boundaries in the right place, the trade-offs well thought out, each service with its clear responsibility—, but if you don't get the VP of product, the orders team, and the dev who arrives in six months to understand it, then the architecture that gets built isn't the one you thought of: it's the one they understood. And what they understood depends entirely on how you communicated it to them. That's why communicating isn't the craft's final ornament, the pretty slide you make when the real work is already done. It's where the real work happens or is lost. This whole module is about learning to communicate an architecture to be understood, not to archive it —two purposes that resemble each other and are opposites—.

This matters because almost all of the world's architecture documentation is written for the wrong purpose. It's written for the archive: the 500-page document that was produced because "we have to document" and that no one ever opened; the diagram that shows the system's 200 components on a single sheet, technically complete and humanly illegible; the wiki that described the system precisely in 2021 and today lies because the code changed and the drawing stayed. All those artifacts exist, take up space, give the feeling that "the system is documented" —and communicate nothing—. The skill this module teaches is the opposite: produce little, but have that little enter the right person's head on the first try. The architect who masters this isn't the one who writes the most; it's the one who chooses what to show, to whom, and with how much detail.

Connection with the module: this lesson is the map, not the territory. Here you don't draw in depth yet; you understand why the six lessons that follow go in the order they go. First the central tool: lesson 2 presents Simon Brown's C4 model —the four zoom levels (Context, Container, Component, Code)—. Then the two maps you'll use most: lesson 3 draws Mercado's Context and Container, one for the business and one for the devs. Then, when to keep going down and when to stop: lesson 4 covers Component and Code and why you almost never draw Code by hand. With the four tools in hand, lesson 5 teaches the most important thing: choosing the right diagram for the audience. Lesson 6 adds the other communication piece, the ADR as the why that travels through time. And lesson 7 vaccinates you against the two big failures: the 500-page document and the spaghetti diagram. Lesson 8, the project, puts you to producing Mercado's communication package for two audiences with your own hands.

Google Maps: you choose the zoom according to what you're looking for

Think about it with a tool you use every week: Google Maps. When you want to understand where a country is in the world, you zoom out until you see continents: borders, oceans, the relative position. At that zoom the streets don't appear, and that's fine —you don't need them to locate the country—. When you want to know how to get from one neighborhood to another within a city, you zoom in: the main avenues appear, the subway stations, the rivers. And when you're already walking and looking for the house number, you zoom in to the maximum: the buildings appear one by one, the corners, the exact entrance. It's the same map —the same city, the same world—, but at each zoom you see a different amount of detail, chosen to answer a different question.

Now notice what no one does: no one tries to navigate a city with the world map —at that zoom you can't even see the streets—, and no one crosses the country with the map of a single street —at that zoom you don't even know which way the highway is—. And most importantly: no one draws a map that shows at the same time the continents and the house numbers. It would be illegible: either you see the world, or you see the street, but not both on the same sheet, because the detail of one covers the shape of the other. The zoom you choose depends entirely on the question you bring and how close you need to look.

That's the C4 model, and it's the whole module condensed into an analogy. Communicating an architecture is exactly choosing the map's zoom according to who's looking and what question they bring. The VP of product brings the world's question: "what does this system do and who does it talk to?" —they want the country map—. The new dev brings the city's question: "what pieces is this made of and where does each one live?" —they want the avenue map—. The dev who's going to get their hands into checkout brings the street's question: "what's inside this specific piece?". A single map doesn't work for the three, just as a single Google Maps zoom doesn't work to locate a country and find a house. The most common mistake when communicating architecture —the one we'll measure in a moment— is giving someone the wrong zoom: showing the VP the street map, or the dev who's going to code the world map. In both cases the person is left unable to do what they came to do.

The case: Mercado, one system and two audiences

Throughout the guide we accompany Mercado, the ecosystem's marketplace, with its five squads —catalog, orders, payments, shipping, platform—. In this module the question isn't how Mercado is organized (that was module 2, Conway): it's how you communicate it. And communicating well starts with noticing that Mercado doesn't have one audience, it has several, and each needs a different map:

• The VP of product comes into a meeting because they want to launch selling to external vendors. They don't care what database you use or what the notifications service is called. They care: what does Mercado do today? who does it talk to —the payment gateway, the shipping carrier's API—? where does the new thing fit? Their question is the world's. A diagram with 30 technical boxes loses them in the first minute and they leave the meeting thinking "this is very complex, I trust the team" —which is the polite way of saying "I understood nothing"—.
• A new dev arrived on Monday and in two weeks has to fix a bug in the order flow. The world map is no use to them —"Mercado sells things" doesn't tell them where to touch—. They need the city's map: what are the deployable pieces? the web app, the API, the database, the search index? which one talks to which? With that they already know where to start reading code. If you give them only the world map, they spend their first week lost, asking everyone where each thing is.

Same system. Two maps. And choosing the wrong map —giving the VP the dev's, or the dev the VP's— is the most common and quietest way to fail at communicating: quiet because no one tells you "you chose the wrong zoom"; the meeting just doesn't advance, or the dev takes three times as long to get going, and no one knows why. Before drawing anything in depth, let's see that failure measured.

Worked example: the same system, four maps —and the mistake of giving the wrong one

C4 puts a name on Mercado's four zooms. Each level answers a question for an audience, and each level carries a different amount of detail —from the Context's 5 boxes to the Code's 40—. The following code doesn't analyze anything technical about the system: it just shows Mercado's four maps and then reproduces the most common mistake, giving the VP the dev's map, to measure how much extra detail they receive.

# The same system (Mercado), different maps according to who's looking.
# C4: each zoom level has an audience and an amount of detail.

c4_levels = {
    "Context":   {"zoom": 1, "elements": 5,  "audience": "VP, business, customers"},
    "Container": {"zoom": 2, "elements": 9,  "audience": "architects, devs, ops"},
    "Component": {"zoom": 3, "elements": 12, "audience": "dev working on THAT container"},
    "Code":      {"zoom": 4, "elements": 40, "audience": "the dev editing THAT code today"},
}

print("Mercado is ONE system. But it admits four maps, one per zoom level:")
print()
print(f"{'Level':<11}{'Zoom':<6}{'Elements':<11}Audience")
print("-" * 62)
for name, info in c4_levels.items():
    print(f"{name:<11}{info['zoom']:<6}{info['elements']:<11}{info['audience']}")
print()

# The most common mistake: giving the VP the dev's map.
vp_needs = "Context"
gave_vp = "Component"
overload = c4_levels[gave_vp]["elements"] - c4_levels[vp_needs]["elements"]
print(f"The VP asked to 'understand the system'. They were shown the {gave_vp} diagram.")
print(f"The right map for the VP ({vp_needs}) has {c4_levels[vp_needs]['elements']} elements.")
print(f"The one they were shown has {c4_levels[gave_vp]['elements']}: {overload} extra boxes that say nothing to them.")
print("Result: the VP gets lost and concludes 'this is very complex, I trust you'.")
print("You didn't communicate. You just archived.")

What to expect. Running it:

Mercado is ONE system. But it admits four maps, one per zoom level:

Level      Zoom  Elements   Audience
--------------------------------------------------------------
Context    1     5          VP, business, customers
Container  2     9          architects, devs, ops
Component  3     12         dev working on THAT container
Code       4     40         the dev editing THAT code today

The VP asked to 'understand the system'. They were shown the Component diagram.
The right map for the VP (Context) has 5 elements.
The one they were shown has 12: 7 extra boxes that say nothing to them.
Result: the VP gets lost and concludes 'this is very complex, I trust you'.
You didn't communicate. You just archived.

Stop at the last two lines, because they're the module's thesis in one sentence. The VP didn't receive less information than they needed: they received more —seven extra boxes, each technically true and humanly useless to them—. And that excess isn't neutral: it's what loses them. The detail a dev uses to work buries the VP. Over-communicating and under-communicating are the same mistake seen from two sides: in both, the person can't do what they came to do. The table above is the complete C4 —four levels, four audiences, four amounts of detail—, and the whole craft of this module is learning to choose the right row for the person in front of you.

Now, what does the right map for the VP —the Context, the 5 boxes— really look like? This simple:

C4Context
    title Mercado - System Context (the VP's map)
    Person(customer, "Customer", "Buys products on Mercado")
    Person(seller, "Seller", "Sells products on Mercado")
    System(mercado, "Mercado", "Online marketplace")
    System_Ext(payments, "Payment Gateway", "Charges the cards")
    System_Ext(carrier, "Carrier API", "Generates labels and tracks shipments")

    Rel(customer, mercado, "Searches and buys")
    Rel(seller, mercado, "Publishes and manages products")
    Rel(mercado, payments, "Charges payments")
    Rel(mercado, carrier, "Requests shipments")

Five boxes and four arrows. The VP looks at this and in thirty seconds understands what Mercado does and who it talks to: customers buy, sellers publish, Mercado charges with an external gateway and ships with an external carrier. Zero technical jargon, zero database, zero framework name. Not because the VP is dumb, but because for their question —"where does opening Mercado to external vendors fit?"— that's the only thing needed to see. That's the world map. In lesson 3 we draw it in depth, alongside the city map the dev needs.

The map of the six lessons

The six lessons that follow go in this order for a reason: first I give you the tool, then I teach you to choose it, and at the end I vaccinate you against the mistakes.

Lesson	What it gives you	Why it goes here
2	The C4 model: the four zoom levels	It's the module's vocabulary; without it you can't talk about "choosing the zoom"
3	Mercado's Context and Container, drawn	They're the two maps you'll use 80% of the time
4	The Component and the Code, and when to stop	To know how far down to go and why you almost never draw Code
5	How to choose the map for the audience	It's the heart: the VP's map isn't the dev's
6	The ADR as communication	The diagram shows the what; the ADR keeps the why that travels through time
7	How to avoid the 500-page doc and the spaghetti	It's the vaccine against the two most common failures

The arc is: first you learn the language of the zooms (2), then you draw the two most useful maps (3) and know how far down to keep going (4). With the tools in hand, you learn the hardest thing, which is choosing the right map for each person (5). Then you add the piece the diagrams don't cover —the why of the decisions, with the ADR (6)— and finally you protect yourself from the two ways to fail (7). Lesson 8 —the project— puts it all together by producing Mercado's communication package for the VP and for a new dev, so you confirm you learned to choose the zoom and not just to draw boxes.

What this module does NOT touch

It's worth marking the frontier from now, because there are neighboring topics that seem to belong here and belong elsewhere.

The architect's role in general was module 1. There we saw what they really do —facilitator, not dictator; the one who makes expensive decisions reversible and communicates them—. This module concentrates on a single dimension of that role: how they communicate. When here we say "the architect explains to the VP", we take for granted why communicating is a central part of the craft (that was M1) and focus on the technique: what map, to whom, with how much detail.

Conway's Law was module 2. There we saw that the organization shapes the system. Here we'll diagram systems, but to communicate them to an audience, not to analyze the org↔architecture dynamic. If in a Mercado diagram it appears that orders and payments share checkout, here that's a fact we communicate clearly; why it happens and how to fix it was Conway.

The ADR's mechanics are the architecture-decisions guide's. The ADR has a structure —Context, Decision, Consequences, Status— and a discipline of when to write it, how to number it, when to mark it as superseded. All that was taught in the sister guide architecture-decisions-and-tradeoffs. Here we do not re-explain its mechanics: we use it as a communication tool —the why of a decision, packaged to travel through time to whoever arrives later—. When in lesson 6 we generate an ADR, the novelty isn't its format (you already know it), it's its role: communicating a decision to a future reader who wasn't in the room.

Leading without authority is module 4. Communicating well is necessary but not sufficient for a decision to be executed: you also have to influence, sustain the conversations that keep it alive, not become the bottleneck. All that —technical leadership without formal authority— is the module that follows. Here we stay at the communication tool; turning it into real execution is M4.

Common mistakes

Believing documenting is the same as communicating (of confused purpose). What happens: someone produces a huge, exhaustive architecture document, with every detail, uploads it to the wiki, and assumes "the system is communicated". No one reads it. Why it happens: the artifact (the document exists) is confused with the effect (someone understood). Documenting is producing the archive; communicating is getting it to enter a head. How to spot it: ask whether anyone used the document last week to make a decision or understand something; if the answer is "it's there just in case", you documented, you didn't communicate. How to fix it: it's the whole module —produce little, aimed at a concrete audience with a concrete question, at the zoom that answers that question—.

Giving everyone the same diagram (of a single audience). What happens: the architect has one system diagram —usually the most detailed, because it's the one that took the most work— and shows it the same to the VP, the new dev, and the ops team. One drowns in detail, another can't find what they're looking for, and only by chance was one of them at the right zoom. Why it happens: making one diagram costs, making four costs more, and it's tempting to believe "one good one works for everyone". How to spot it: if you use the same drawing in a business meeting and in a technical onboarding, you're giving someone the wrong zoom. How to fix it: lesson 5 —match audience with level; the VP's map isn't the dev's, and that's not optional—.

Putting everything on a single sheet (of fear of omitting). What happens: the diagram shows the external systems, the containers, the internal components, and even some classes, all together, with a hundred crossing arrows —the spaghetti diagram—. It looks impressive and communicates nothing, because it mixes abstraction levels the head can't process at once. Why it happens: out of fear of omitting something important, everything is included; and because a dense diagram gives a false sense of rigor ("look how much I know about the system"). How to spot it: if your diagram has one kind of box that's "the whole system" and another that's "a function", on the same sheet, you're mixing the world map with the street map. How to fix it: lesson 7 —one diagram, one level; completeness lives in the set of diagrams, not in each one—.

Exercises

Exercise 1 — What zoom does each one ask for? Three people ask you for "a diagram of Mercado": (a) an investor evaluating putting money into the company; (b) an engineer from another team who's going to integrate their system with Mercado's API; (c) a developer who just received the ticket to fix a specific bug in how the tax is computed inside the checkout service. Without drawing anything, say which C4 level (Context, Container, Component, or Code) you'd give each one and why.

See solution

(a) The investor → Context. They bring the world's question: what does the company do, who does it connect with, how big is the scope? They don't care —nor would they understand— what the database is called. The Context (5 boxes, zero jargon) shows them that Mercado is a marketplace connecting customers and sellers and depends on a payment gateway and a shipping carrier. That's exactly their level.

(b) The integrating engineer → Container. They're not going to get their hands into Mercado's internal code, but they need to know which piece their system talks to: is there an API? what does it expose? how is it deployed? The Container (level 2, the city map) shows them the deployable pieces and their boundaries, which is exactly what they need to integrate without having to understand each container's guts. Giving them the Context would be too little (they don't see the API); giving them the Component would be too much (they don't care how the API is split inside).

(c) The developer with the ticket → Component (and maybe Code). They're going to work inside a specific piece —the checkout service— on a specific detail —the tax calculation—. They need the neighborhood map: what components are inside checkout, which one calculates taxes, what it depends on. That's the Component (level 3). The Code (level 4) almost never needs to be drawn: to see the exact classes of the calculation, it's more useful for them to open the real code in their IDE than a diagram that will go out of date. The rule: go down to the Component to orient yourself inside the piece; for the final detail, go to the code, not to a drawing of the code.

Exercise 2 — The diagram that didn't communicate. An architect presents to the executive committee (VPs of product, finance, and operations) the plan to scale Mercado 10x. They project a single diagram with 34 boxes: the 5 containers, their internal components, the message queues, the databases, the caches, and the external integrations, all connected with about 50 arrows. The executives nod, ask two vague questions, and approve the budget "trusting the team". Why is this a communication failure even though the project was approved? What should have been shown?

See solution

It's a failure because the executives understood nothing —they approved out of trust, not out of understanding—, and that has a cost that appears later: when the project gets complicated and more budget has to be requested or a delay explained, the committee won't have the mental model to follow the conversation, because they never had it. "They approved" isn't the same as "they understood"; the architect got the yes, but didn't build the understanding they'll need in the next ten meetings. The "we trust the team" is the alarm signal: it's what people say when the diagram lost them.

The technical problem is the wrong zoom and the mixing of levels: 34 boxes with internal components, queues, and caches is the city-plus-neighborhood-plus-street map, all stacked, for an audience that brings the world's question. They should have shown a Context (level 1): Mercado, its users, its external dependencies, and on top of that, marked, where the 10x growth impacts —maybe "here's where the traffic multiplies and that's why the investment is needed"—. Five or six boxes, one clear idea, one decision the committee can really evaluate. The detail of the 34 components exists and is valid, but it's the map for the technical team, not for the committee. One diagram, one level, one audience.

Exercise 3 — Communicating isn't just drawing. The Mercado team decided a year ago to extract checkout to its own service. The Container diagram already shows the new Checkout Service as a separate box, correctly. Today a new dev arrives, looks at the diagram, and asks: "why is checkout separated from orders if they're clearly so related? It seems simpler to join them." The diagram, on its own, doesn't answer that question. What's missing from the communication, and what tool from this module resolves it?

See solution

The diagram lacks the why. A diagram communicates the what very well —what pieces there are, how they connect, what the system looks like today—, but it's mute about why the system is this way and not another. The new dev sees the right picture (checkout separated) but doesn't have the reasoning behind it, so their instinct —"it seems simpler to join them"— is reasonable and dangerous: without knowing the reason for the separation, they could propose undoing it and repeat the problem the separation solved.

The tool that resolves it is the ADR as communication (lesson 6). An ADR titled "Extract checkout to its own service" that records the context (checkout lived in orders but payments touched it on every change; two squads coordinating the business's most critical flow), the decision (a stream-aligned team owning the full flow), and the consequences (faster changes, in exchange for one more network call). That ADR is the why that travels through time: the new dev reads it, understands that the separation wasn't a whim but the solution to a real coordination pain, and no longer proposes undoing it. The diagram shows the picture; the ADR tells the story of why the picture looks like this. You need both.

Summary and next step

In this lesson you met the thesis that holds up the module: an architecture decision no one understands doesn't exist —communicating isn't the craft's ornament, it's where the architecture happens or is lost—. With Google Maps you saw the heart of C4: you choose the zoom according to the question you bring, and no one navigates a city with the world map nor draws the continents and the house numbers on the same sheet. You met Mercado as a system with several audiences —the VP who brings the world's question, the new dev who brings the city's— and saw, executed, that giving someone the wrong zoom isn't giving them less than they need: sometimes it's giving them more, seven boxes of excess that bury them. And you saw Mercado's first map, the five-box Context for the VP.

Before moving on you should be able to: name the difference between documenting (producing the archive) and communicating (someone understanding); explain the zoom analogy and why a single map doesn't work for all audiences; and recognize that a diagram communicates the what but not the why —for that you need the ADR—.

What follows is learning the vocabulary that makes everything else possible. In lesson 2 you'll meet Simon Brown's C4 model in depth: the four zoom levels —Context, Container, Component, Code—, what question each one answers exactly, what audience it serves, and why "a simple notation with four levels" beats the soup of symbols almost no one remembers. It's the step from "I sense you have to choose the zoom" to "I have four named zooms and I know what each one does".

Resources

• Simon Brown — The C4 model (c4model.com) — the source of the whole module, written by the model's creator. It explains the four levels with examples and the philosophy of "one map at different zooms". Free, concise, and with reference notation; the mandatory starting point.
• Gregor Hohpe — The Software Architect Elevator — the book that treats the architect's communication as their central skill: going up to the penthouse (business) and down to the machine room (code), translating between levels. The idea of "communicate by levels according to the audience" that holds up this whole module.
• arc42 — architecture documentation template (arc42.org) — a proven template for documenting architectures in a way that survives; useful as a skeleton of "what to communicate and in what order". We'll see it in depth in the documentation guide; here, as a structure reference.
• Martin Fowler — Software Architecture Guide — Fowler's hub on architecture, with essays on why architecture matters and how to communicate it. A good conceptual counterpoint to C4: the why of communicating, not just the how.