"Here's the
architecture, good luck."
It's your first week. Someone shares an architecture doc — fifteen boxes, twenty lines, no legend, mixing services with classes with deployment regions all in the same picture. You squint. You ask "what does this arrow mean?" The senior engineer says "oh that's just the message queue, you'll figure it out." Will you? This scene plays out a million times a year. The difference between engineers who become productive in week one vs week six is largely the ability to read diagrams someone else drew years ago in some now-forgotten meeting.
"What am I even looking at?"
"Got it."
That gap — 45 minutes vs 5 — isn't about being smarter. It's about knowing what kind of diagram you're looking at, what its conventions are, and how to extract the answer you need without having to interview the original author. The good news: there's a small, standard visual vocabulary that covers 90% of architecture diagrams you'll encounter. Once you know it, every diagram becomes legible.
Four levels.
Each zooms in.
The C4 model, created by Simon Brown, is the most widely adopted convention for architecture diagrams. The four C's stand for Context, Containers, Components, Code — each level zooms in on a piece of the previous one, like Google Maps stepping from country to city to street to building. The point isn't to draw all four for every system. It's to know which level answers the question you have, and to stay at that level instead of mixing scales (the #1 cause of unreadable diagrams).
// THE FOUR C'S · ZOOM LEVELS
Context
The whole system as one box, plus users and external systems it talks to. No internal detail. Audience: anyone — execs, PMs, new hires.
non-technical OKContainer
Zoom into the system box. Show each independently deployable thing: web app, API, mobile app, database, queue. Most useful day-to-day diagram.
developersComponent
Zoom into one container. Show its internal modules / services: auth, billing, search. Helps the team owning that container.
team / module ownersCode
Zoom into a component. Classes, structs, interfaces. Usually skipped — your IDE shows this better than any drawing. Mostly auto-generated when needed.
just code-readThe rule that matters: one diagram, one level. A diagram that mixes Containers and Components confuses everyone because the same box might be "a deployable service" or "a class within a service." When you read a diagram, the first question to ask yourself is what level is this? Once you know, every other element fits into a known category — and ambiguous elements jump out as drawing errors rather than puzzles.
The other thing C4 gives you for free is standard notation. Each shape has a meaning. Each line has a label describing the relationship ("uses API to fetch profile", not a bare arrow). A legend tells you which shape is which. This is the bare minimum for a diagram that future engineers will actually be able to read.
Other diagrams
you'll meet.
C4 covers the static structure — what the system is. But you'll see plenty of other diagram types, each answering a different question. Knowing which is which lets you pull useful info out of any architecture doc.
// THE COMMON ZOO OF DIAGRAM TYPES
draft, pending, shipped) connected by arrows labeled with transitions. Crucial for any entity with a complex lifecycle — orders, subscriptions, support tickets.You'll rarely see all of these in one place. A well-organized architecture doc usually has a C4 Container view as the "main map," a sequence diagram for the most important flow, an ER diagram for the data, and a deployment diagram for ops. Anything more, and you're probably over-documenting; anything less, and there are blind spots. If you ever write the architecture doc, this is the template.
Now read
a real diagram.
Below: the same image-sharing app from M.18, drawn at each C4 level. Click on any yellow zoomable box to drill down a level. Watch the level breadcrumb update. Read the "what you can answer here" panel for each level. You'll see how the same system shows different things depending on how far back you stand.
// LEVEL 1 — SYSTEM CONTEXT
System Context
// questions this level answers
When a diagram
is lying to you.
Not every diagram is good. Bad diagrams aren't just unhelpful — they actively mislead. Once you start reading carefully, you'll notice these red flags constantly. Spotting them is the difference between trusting a diagram and confirming what it claims with code.
No legend, no notation
Every shape and arrow style means something — but only if you say what. If there's no legend, you're guessing what a dashed line vs solid line vs double arrow means. Ask. Or, if you're the author, label everything. Implicit notation is no notation.
Mixed zoom levels
Containers and classes in the same picture. A box labeled "Auth Service" next to one labeled "UserModel". Different scales of thing. Always means the author drew "what came to mind" rather than picking a level. Read with extra skepticism.
Unlabeled arrows
An arrow from A to B can mean ten different things: A calls B's API, A reads from B, A publishes events that B consumes, A deploys to B, A depends on B's type. An unlabeled arrow is an inkblot test. Ask the author. Or write your own label and confirm.
Last updated: 2 years ago
The diagram shows a "Recommendations Service" but you grep the codebase and find no such service. Or vice versa: there are 12 services in production and 5 on the diagram. Architecture diagrams rot fast. Check the date. Cross-reference with reality. Update what you can.
"Big ball of mud"
Every box connects to every other box. Arrows criss-cross. There's no clear flow. Sometimes this reflects reality — the system genuinely is tangled. Sometimes it's just a lazy drawing. Either way it tells you something: either the system needs refactoring, or the documentation does.
Boxes labeled with brand names
"Stripe" "Postgres" "Kafka" — naming the tech instead of the role. "Stripe" tells you the vendor, not the function. Better: "Payment Provider (Stripe)" — role first, vendor in parentheses. The first version lets you swap vendors later without re-drawing.
These aren't just author mistakes — they accumulate over time. Diagrams drawn well three years ago decay as the team forgets to update them; small messes compound. The most important thing you can do when reading an existing diagram is to compare it against current code or current production state. If they disagree, the diagram is wrong (the code/runtime is always ground truth). Either fix the diagram or know to ignore it.
Vocabulary,
for the whiteboard.
These terms show up in every architecture review, RFC, and design doc you'll touch. Get fluent so you can both read and contribute.
Five questions.
Read between the boxes.
Test the diagram-reading instinct. Click an answer; explanation drops in instantly.
Cartographer.
You can navigate any architecture diagram now. One module left — the interview toolkit that ties everything together.
Three ideas to
carry forward.
Diagrams are the universal language of architecture. Reading them is half the skill of designing them.
One diagram, one level
Context, Container, Component, Code. Pick one for the question you're answering. Mixing levels is the #1 reason diagrams are unreadable.
Notation matters
Labels on every arrow. Legend for every shape. A diagram without a key is an inkblot test, not documentation.
Code is ground truth
Diagrams rot. When the diagram and the code disagree, trust the code. The most useful first task at a new job is updating someone else's diagram.