Level 4: Code

5 min read

We've arrived at the deepest zoom the C4 model offers. We walked the streets at the Component level; now we step through the front door of a single building and look at the individual rooms. The Code diagram shows how one component is implemented under the hood — and it comes with an unusual piece of advice from the model's own creator: most of the time, don't bother drawing it.

Let's explain both what it is and why that advice makes sense.

What the Code diagram shows

Pick a single component — say, the Payment Service from our Component diagram — and open it up. Inside, you finally reach the actual code: the classes, interfaces, functions, and their relationships. This is the level of detail traditionally captured by a UML class diagram: which class implements which interface, what inherits from what, which objects hold references to which.

In other words, this is the "nitty-gritty." It answers questions like: what are the concrete types that make up this component? How do they relate — inheritance, composition, dependency? What does the internal object model actually look like?

If you've ever generated a class diagram from your IDE, you've already seen a Level 4 diagram.

Why Simon Brown recommends skipping it

Here's the twist. Simon Brown, who created the C4 model, explicitly considers this level optional — and recommends most teams skip it entirely. This isn't laziness; it's a deliberate stance rooted in a few hard truths about how software actually works.

The code changes too fast. Component and container structure is relatively stable — it might shift with a significant refactor. But the classes inside a component change constantly, sometimes several times a day. A hand-drawn class diagram is therefore obsolete almost the moment you finish it. You'd spend more time maintaining the picture than writing the code it describes, and it would still be wrong.

The code is already the best documentation of itself. At this level of detail, the source code is the source of truth. Anyone who needs to know the exact class structure can open the codebase and read it — or better, ask their IDE to draw it. There's little value in maintaining a second, hand-crafted representation that can only ever be a stale copy of what the code already says perfectly.

It rarely aids understanding at the architectural level. The whole promise of C4 is to help people reason about a system's architecture. Class-level detail is usually too granular to serve that goal — it's the difference between understanding a city's layout and memorizing the wiring diagram of one house. Most architectural conversations are won or lost at Levels 1 and 2, occasionally 3. Level 4 seldom moves the needle.

When it is worth drawing

"Usually skip it" is not "never draw it." There are narrow cases where a Code-level diagram earns its keep:

A genuinely complex or subtle component whose internal design isn't obvious from a quick read — a tricky state machine, an intricate algorithm, a non-trivial design-pattern implementation.
Teaching or onboarding around a specific, tricky piece of code where a picture genuinely accelerates understanding.
Design discussions where you're sketching a proposed class structure before writing it — here the diagram is a thinking tool, not documentation to be maintained.

The common thread: draw a Code diagram when the picture provides insight the code itself doesn't make obvious, and be ready to throw it away rather than maintain it.

Generate it, don't draw it

If you do need a Code-level view, the strongly preferred approach is to generate it automatically from the source code, on demand, rather than draw and maintain it by hand. Modern IDEs (IntelliJ, Visual Studio, and others) and various tooling can produce class diagrams directly from the codebase at the press of a button. Because it's generated from the real code, it's always accurate, costs nothing to keep up to date, and can be discarded the instant you're done with it. This neatly sidesteps the staleness problem that makes hand-drawn Code diagrams such a poor investment.

This "generate rather than maintain" philosophy is a preview of a bigger idea we'll explore next: treating your architecture diagrams as something derived from a single source of truth, rather than hand-crafted artifacts that immediately begin to rot.

The takeaway

The Code diagram completes the C4 model conceptually — it's the final, deepest zoom, the individual rooms inside the building. But in day-to-day practice, most teams get everything they need from Levels 1 through 3, and let their IDE handle Level 4 on the rare occasions it's needed. If you take one thing from this section, let it be this: you are not failing at C4 by not drawing Code diagrams. You're doing it right.

With the four core levels behind us, you might think we're done zooming. But the four levels only capture the static structure of a system — they don't show how it behaves at runtime or where it actually runs. For that, C4 offers a few supporting diagrams, which we'll cover next.

Previous: ← Level 3: Component · Next: Supporting Diagrams →