Module 3: Communicating Architecture

5. The right diagram for the audience

Next →

Overview

By the end of this lesson you'll master the skill that governs all the others in this module: choosing the right diagram for the audience in front of you. You already know how to draw the four C4 levels; now you learn the hardest thing, which is deciding which of the four you give each person. The thesis is direct and has consequences: the map for the VP isn't the same as for the dev. It's not that one is "better" and another "worse" —both are correct—; it's that each audience brings a different question and needs a different zoom to answer it. Giving someone the wrong level isn't an aesthetic detail: it's the difference between communicating and not communicating. And the error goes in both directions —a level too high drowns the person in detail, a level too low leaves them unable to work—, so it's not enough to "always simplify" or "always detail": you have to aim at the level the audience needs.

This matters because it's the most common and most expensive communication mistake, and almost no one diagnoses it as what it is. When a business meeting doesn't advance, or a new dev takes weeks to get going, rarely does anyone say "we gave them the wrong zoom" —the blame goes to "the system is very complex", to "the dev is slow", to "the VP isn't technical"—. But very often the real cause is that the communication aimed at the wrong level: the VP was shown the street map, the dev was shown the world map. The architect who learns to match audience with level fixes, in a single stroke, an enormous amount of friction others attribute to diffuse causes. It's one of the cheapest and most ignored levers of the craft.

Connection with the module: in lessons 2, 3, and 4 you built and drew the four tools —the four C4 levels—. This lesson is where you learn to use them with judgment: not how to draw each level, but which to choose for whom. It's the heart of the module, the reason everything before exists. In lesson 6 you'll add the piece the diagrams don't cover —the why, with the ADR—, and in lesson 7 you'll protect yourself from the failures (the giant doc, the spaghetti). And in the project (lesson 8) you'll practice exactly this skill: producing Mercado's package by choosing the right level for the VP and for the dev.

The doctor who adjusts the explanation to the patient

Think of a good doctor who just read your tests and has to explain a diagnosis to you. If they were talking to a fellow doctor, they'd use the precise technical terms: the exact lab values, the Latin name of the condition, the pathophysiological mechanism. To you, who aren't a doctor, they say the same thing but at another level: "your sugar is a bit high; if we change the diet and you walk half an hour a day, we control it". They're not lying to you or hiding information: they're giving you the zoom you can use to act. Telling you the complete pathophysiological mechanism wouldn't make you healthier; it would overwhelm you and you'd leave the office not knowing what to do.

Now reverse the situation. If that same doctor told their specialist colleague "the sugar is a bit high, we have to watch the diet", the colleague would fall short —they need the exact values, the evolution, the differentials to decide a treatment—. The level that was perfect for you would be insufficient for the specialist. And here's the key: the error goes in both directions. Giving the patient the specialist's explanation drowns them; giving the specialist the patient's explanation leaves them unable to work. A good doctor doesn't "always simplify" or "always detail": they read who's in front of them and aim at the level that person can use.

Communicating architecture is exactly that. The VP is the patient: they need the Context ("Mercado connects buyers and sellers, charges and ships") to be able to decide, and the technical detail overwhelms them. The dev is the specialist: they need the Container or the Component to be able to work, and the Context falls short. There's no "correct" diagram in the abstract —there's a correct diagram for each person—. The architect, like the doctor, reads their audience and adjusts the zoom.

Mercado's two scripts

Let's land it on the two concrete conversations Mercado's architect has this week.

Script 1: the meeting with the VP of product. The VP wants to launch selling to external vendors by API and needs to understand where that fits. The architect puts the Context (level 1) on the screen: Mercado as a box, surrounded by customers, sellers, the payment gateway, and the shipping carrier. They point to the relationship with "sellers" and say: "today sellers publish through the web; what you propose is that they can also do it through an API, here". The VP understands it in a minute, sees the implication (more sellers, more load on payments and shipping), and the conversation advances to what matters: budget, priorities, business risks. Five boxes did the work. If the architect had projected the Container with its nine technical pieces, the VP would have asked "what's Elasticsearch?" and the meeting would have gotten lost in a tutorial.

Script 2: the new dev's onboarding. The new dev arrived on Monday and in two weeks has to fix a bug in the order flow. The architect shows them the Container (level 2): Mercado's five pieces, their technologies, how a request flows from the browser to the API to the database. The dev sees where the order flow lives (the API), what surrounds it, and starts reading code with a map in their head. If the bug were in checkout —tangled—, the architect would go down one more rung and show them the Component of checkout, so they locate the Tax Calculator without getting lost. If instead they'd shown them only the Context —"Mercado sells things"—, the dev would have spent their first week asking everyone where each thing is, because the world map doesn't say where to touch the code.

Same system, two scripts, two levels. The skill isn't drawing —you already know that— it's choosing. Let's turn that choice into something measurable.

Worked example: the recommender and the mismatch detector

The level choice can be systematized: for each audience there's a recommended level, and given a level someone actually received, you can detect the mismatch and its direction —too high (drowns) or too low (can't work)—. The following code does both: first it prints the audience→recommended level table, and then it audits what map each one received this week in Mercado, marking each mismatch with its direction and its cost.

# The right map for the audience.
# Recommender: for each audience, the C4 level it needs.
# Detector: given (audience, shown level), it marks the mismatch and its direction.

level_rank = {"Context": 1, "Container": 2, "Component": 3, "Code": 4}

recommended = {
    "VP of product":               "Context",
    "customer or investor":        "Context",
    "architect from another team": "Container",
    "new dev on the team":         "Container",
    "dev working on checkout":     "Component",
    "dev editing that file":       "Code",
}

print("Audience -> recommended C4 level")
print("-" * 55)
for audience, level in recommended.items():
    print(f"  {audience:<30} {level}")
print()

# Audit: what map each one received this week in Mercado.
shown = [
    ("VP of product",               "Component"),
    ("new dev on the team",         "Context"),
    ("dev working on checkout",     "Component"),  # correct
    ("customer or investor",        "Container"),
]

print("Audit of the week (what map each one received):")
print("-" * 55)
for audience, level in shown:
    want = recommended[audience]
    if level == want:
        print(f"  OK   {audience:<30} {level:<10} correct")
    else:
        gap = level_rank[level] - level_rank[want]
        if gap > 0:
            print(f"  BAD  {audience:<30} {level:<10} +{gap} too high (drowns in detail; wanted {want})")
        else:
            print(f"  BAD  {audience:<30} {level:<10} {gap} too low (can't work; wanted {want})")

What to expect. Running it:

Audience -> recommended C4 level
-------------------------------------------------------
  VP of product                  Context
  customer or investor           Context
  architect from another team    Container
  new dev on the team            Container
  dev working on checkout        Component
  dev editing that file          Code

Audit of the week (what map each one received):
-------------------------------------------------------
  BAD  VP of product                  Component  +2 too high (drowns in detail; wanted Context)
  BAD  new dev on the team            Context    -1 too low (can't work; wanted Container)
  OK   dev working on checkout        Component  correct
  BAD  customer or investor           Container  +1 too high (drowns in detail; wanted Context)

Read the audit carefully, because it tells the whole story. Three of four communications failed this week, and they failed in both directions. The VP received Component: two levels too high, drowns —the case of the patient given the specialist's explanation—. The new dev received Context: one level too low, can't work —the specialist given the patient's explanation—. The customer received Container: one level too high, again detail they can't use. Only the checkout dev, who received Component, hit the target.

Notice what the "direction" column reveals: the mismatch isn't always "they gave too much". Twice it was too high (VP, customer) and once too low (new dev). That's why the rule can't be "always simplify" —that would fix the VP and the customer but worsen the new dev, who already received too little—. The correct rule is aim: read the audience's question and give them the level that answers it, not one more or one less. The recommender above isn't a magic oracle; it's the habit of asking yourself, before showing any diagram, "who's looking at this and what question do they bring?" —and that question, asked in time, avoids the three failures of the week—.

The cost of each direction of the mismatch

It's worth understanding why each direction of the mismatch does harm, because they're different harms.

Level too high: drowning in detail. When you give someone a finer zoom than they need, you don't give them "extra information they might use" —you give them noise that covers the signal—. The VP who sees the checkout Component doesn't think "great, now I know more"; they think "I understand nothing of this, better I trust the team". Excess detail doesn't add comprehension: it subtracts it, because the main idea (what the system does, where the new thing fits) gets buried under pieces the audience can't process. The cost is a decision made blind or an approval by faith, not by understanding —and that's charged later, when that person doesn't have the mental model for the next conversation—.

Level too low: paralysis. When you give someone a coarser zoom than they need, you leave them without the information to act. The new dev who only sees the Context knows "Mercado sells things" but doesn't know where to touch the code, so they can't start: they have to go person by person asking "where's the order flow?", reconstructing by hand the map they should have received. The cost is lost time and dependence on others —the two-week onboarding that should have been two days—. Paralysis is more visible than drowning (the dev knows they're stuck), but just as expensive.

The lesson of having both directions in view: there's no safe default. "Always detail" drowns the ones up top; "always simplify" paralyzes the ones down below. The only rule that works is reading the audience and aiming. That's why this skill is judgment, not a recipe.

When you don't know the audience: ask for the question

The recommender assumes you already know who's looking —"VP of product", "new dev"—. But in real life you're often asked for "a diagram of the system" without being told for whom or for what, and choosing the level blind is guessing. The fix isn't memorizing more audience categories: it's learning to ask for the question before drawing anything.

The technique is a single question, asked in time: "what are you going to do with this diagram?" —or its variant, "what decision or task brings you here?"—. The answer gives you the level directly, because the C4 level isn't determined by the person's title but by the task they bring:

  • If they answer "I want to understand what the system does to decide whether we invest / approve / integrate at a high level" → it's a world task → Context.
  • If they answer "I'm going to work on the system and need to orient myself" → it's a city task → Container.
  • If they answer "I'm going to modify this specific piece inside" → it's a neighborhood task → Component.

Notice that the same person can need different levels depending on the task: the same VP who today wants the Context to approve a project, tomorrow —if they get into reviewing why a module is slow— might need you to explain something from the Container. Don't label the person once and for all; read today's question. That's why the recommender is a starting point, not a law: it maps typical audiences to typical levels, but the most reliable signal is always the concrete task the person comes to solve.

There's a secondary benefit of asking for the question: it protects you from the technical-vanity error. When you start with "what are you going to do with this?", your brain orients toward what the person needs to do instead of toward what you want to show. The conversation stops being "let me show you what I know about the system" and becomes "let me give you what you need for your task" —which is, exactly, the difference between communicating and showing off—. A ten-second question before opening the diagram avoids most of the mismatches the worked example measured.

And a trick that closes the circle: write the audience in the diagram's own title. Instead of titling a sheet "Mercado Architecture" —which doesn't say who it's for—, title it "Mercado — System Context (for business)" or "Mercado — Containers (for development)". This has two effects. For you, the one drawing: putting the audience in the title forces you to decide it before drawing, so you can no longer fall into the diagram-for-no-one. For whoever receives it later —maybe months later, without you in the room—: the title tells them at a glance whether this is their map or whether they should look for another level. A diagram with no declared audience is a diagram that invites the mismatch, because anyone opens it without knowing whether it's for them. The titles of this module's C4 diagrams carry that mark on purpose ("the VP's map", "the dev's map"): it's not decoration, it's part of communicating the level.

Common mistakes

Recycling the most detailed diagram for everyone (of lazy reuse). What happens: the architect made a very complete Container (it took work) and uses it the same with the VP, the new dev, and the customer, because "it's already made". One drowns, another does fine by chance, another can't find what they're looking for. Why it happens: making a diagram costs, and reusing the one that already exists feels efficient. How to spot it: if the same diagram file appears in a business meeting and in a technical onboarding, you're recycling the wrong zoom for at least one audience. How to fix it: have the two or three diagrams of the system ready (Context, Container, and the critical Component) and choose which to show according to who enters the room; the cost of having several pays for itself by not losing any conversation.

Believing "more detail" is always "more professional" (of technical vanity). What happens: the architect shows the densest diagram they have because exhibiting technical mastery feels like doing the job well —"look at everything I know about the system"—. The business audience is impressed and lost. Why it happens: impressing is confused with communicating; detail gives status. How to spot it: if you choose what to show by what makes you look competent instead of by what the audience can use, it's vanity, not communication. How to fix it: measure success by what the audience understood and could do, not by how impressed they looked; for the VP, five boxes that let them decide are worth more than thirty that leave them mute.

Over-simplifying "so as not to overwhelm" the technical person (of overcorrection). What happens: someone learned that "you have to simplify" and now gives everyone the Context, including the new dev who needs the Container. The dev is left unable to work. Why it happens: "simplify for the business" is taken as a universal rule instead of as one of the two directions. How to spot it: if a technical person asks "and inside, how is it?" and you insist on the high-level view, you over-simplified. How to fix it: remember the error goes in both directions —to the business person you give the coarse zoom, to the technical one the fine—; the rule isn't to simplify, it's to aim at the level that answers the question of whoever's in front of you.

Exercises

Exercise 1 — Match and detect. Four people received a Mercado diagram this week. Say whether the level was correct and, if not, in which direction it failed (too high / too low) and what they should have received: (a) an investor received the Container; (b) a dev who's going to refactor the Tax Calculator received the checkout Component; (c) the VP of operations received the class diagram of the shipping module; (d) an engineer from a partner team who's going to integrate by API received the Context.

See solution
  • (a) Investor with Container → too high (+1). The investor wants the Context (what it is, who it talks to). The Container throws technical pieces at them they don't evaluate; they drown a bit. They should have received Context.
  • (b) Dev refactoring Tax Calculator with the checkout Component → correct. They're going to work inside that piece; the Component shows them where the Tax Calculator lives and what surrounds it. Exact level. (For the final class detail, they'd open the code, not a Code diagram.)
  • (c) VP of operations with a class diagram → too high (+3, the worst mismatch). A VP with a Code-level diagram is three levels above what they can use; total drowning. They should have received Context (or at most a bounded Container if their question was very operational).
  • (d) Engineer integrating by API with Context → too low (-1). They need to know which piece they talk to and how —that's Container—. The Context doesn't show them the API. They can't integrate with what they received. They should have received Container.

Two too high, one too low, one correct: the real pattern: the mismatch goes in both directions and you have to read each case, not apply a single rule.

Exercise 2 — The rule that doesn't work. A team, fed up with losing meetings with business, adopts the rule: "from now on, we show everyone only the Context; that way no one is overwhelmed". What new problem does this rule create, and why is "always simplify" not the solution? Propose the correct rule.

See solution

The rule creates the opposite problem: it paralyzes the technical audiences. The new dev, the integrating engineer, the ops team —all who need the Container or the Component to work— now receive only the Context, which falls short. They fixed the business drowning at the cost of the technical paralysis: the devs go back to losing days reconstructing by hand the city map the rule denies them. Changing "always detail" for "always simplify" doesn't eliminate the mismatch; it just moves it from one audience to another.

"Always simplify" doesn't work because the communication error goes in both directions: there are those who receive too much (and drown) and those who receive too little (and get paralyzed). No single-direction rule —neither "detail" nor "simplify"— hits both audiences, because they have opposite needs. The correct rule is aim: for each person, give the level that answers their question —Context to the business, Container to the dev orienting themselves, Component to the one working inside a piece—. It costs more (you have to read each audience and have several diagrams ready) but it's the only one that communicates to everyone. The comfort of a single rule is always paid with a poorly-served audience.

Exercise 3 — The same meeting, two audiences. Mercado's architect presents the plan to open the API to external vendors before a mixed room: the VP of product and two developers who are going to build it are there. They can't give the room a single level without failing someone. How do you structure the communication to serve both audiences in the same meeting?

See solution

The key is not to look for "the diagram that serves both" —it doesn't exist, because they have different questions— but to sequence the levels and be explicit about who each one is for. A structure that works:

  1. Start with the Context, for everyone. "Here's Mercado and its world; what we propose is this new relationship —external vendors by API—, here." With this the VP has everything they need for their decision (fit, business implications, risk) and the devs have the frame. No one drowns, no one gets lost: the Context is the common ground.
  2. Announce the zoom change. "With that, VP, you have the picture to decide. Now I go down a level for the technical team; if you want to follow it, welcome, but the business decision is already on the table." This gives the VP permission to disconnect without feeling excluded, and the devs to receive their part.
  3. Go down to the Container (and the checkout Component if applicable), for the devs. Now you do show where the new API lives, what pieces it touches, how it flows. The devs get their work map.

The general technique: the Context is the common language where every mixed meeting starts, and from there you go down by levels announcing the audience change. That way each one receives their zoom without the other drowning or getting lost, and —bonus— the act of announcing "now I go down a level" teaches the room the mental model that there are levels. It's exactly going up and down the architect's elevator, live.

Summary and next step

In this lesson you learned the skill that governs the whole module: choosing the right diagram for the audience. With the doctor who adjusts the explanation to the patient you saw that there's no "correct" diagram in the abstract —there's one correct for each person—, and that the error goes in both directions: a level too high drowns in detail, a level too low leaves them unable to work. You measured it: in a week of Mercado, three of four communications failed —two by excess (VP, customer), one by defect (new dev)—, which proves that "always simplify" isn't the solution. The rule that works is aim: read the audience's question and give the level that answers it, not one more or one less.

Before moving on you should be able to: match an audience with its C4 level and justify why; diagnose a mismatch and name its direction (too high / too low) and its cost (drowning / paralysis); and structure a mixed meeting by sequencing levels from the common Context.

What follows adds the piece the diagrams, on their own, don't cover. 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. In lesson 6 you'll use the ADR as a communication tool: the why of a decision, packaged to travel through time to the dev who arrives in two years and needs to understand why Mercado is the way it is, without being able to ask anyone. It's the step from "I know how to show the picture of the system at the right level" to "I know how to leave recorded the story of why the picture looks this way".

Resources

← Previous4. Component and Code: when to go down and when to stopNext →6. The ADR as communication: the why that travels through time