Level 4
The Code diagram
Classes, interfaces and their relationships inside a single component. The level almost everybody draws first and almost nobody should maintain by hand.
What it is for
Level 4 is a UML class diagram (or an ER diagram, or an entity model) scoped to one component. It shows the types, their key members and how they relate.
Simon Brown's own advice is to draw it rarely, and only if it adds value — because the source code already is this diagram, and it is always right.
The cases where it earns its place
- A genuinely subtle design — A state machine, a rules engine, a pricing model where the type relationships are the design.
- A data model — ER diagrams are Level 4 material and age far better than class diagrams.
- Teaching material — Onboarding docs where the point is to explain a pattern, not to mirror the code.
- A design not yet written — Sketching a component before it exists is cheap; keeping the sketch afterwards is not.
Generate, do not maintain
If you want Level 4 for an existing component, produce it on demand from the source — IDE class-diagram tooling, a doc generator, or a schema dump for the data model. A generated diagram cannot drift, and a diagram that cannot drift can be trusted.
The one thing worth committing next to the code is the prose: why these types exist, which invariant each one protects, what happens when someone adds a fifth subclass.
The exception: data models
The database schema is the Level 4 artefact people actually reread. Tables, columns, keys and cardinalities change slowly, they constrain everything above them, and a wrong assumption about a foreign key causes real outages.
Keeping the ER model attached to the database container — rather than in a separate modelling tool — is one of the highest-value things a team can do to its documentation.
Frequently asked
Should I commit C4 Code diagrams to the repository?
Usually not. The source is the authority and hand-maintained class diagrams drift within weeks. Commit the reasoning; generate the picture.
Is an ER diagram a C4 Code diagram?
It sits at the same level of zoom: the internal structure of one component or data store. It is the Level 4 artefact most worth keeping, because schemas change slowly and constrain everything above them.
The guide
The rest of the guide
Eight short pages covering the four levels, the notation, the comparisons people ask about, and the tooling decisions that only hurt six months in.
Level 1
The System Context diagram
One box for your system, the people who use it, and the systems it depends on. It is the only architecture diagram that a product manager, a security reviewer and a new engineer can all read on their first day.
Level 2
The Container diagram
The separately deployable pieces inside your system and the technology each one is built with. If a team draws only one architecture diagram, this is the one that earns its keep.
Level 3
The Component diagram
The major building blocks inside one container, what each is responsible for, and how they collaborate. Drawn per container, and only for the containers that are genuinely hard.
Level 4
The Code diagram
Classes, interfaces and their relationships inside a single component. The level almost everybody draws first and almost nobody should maintain by hand.
Comparison
C4 vs UML, ArchiMate and "boxes and lines"
C4 is not competing with UML — it is solving a different problem. Knowing which problem each one solves is what stops an architecture review turning into a notation argument.
Comparison
C4 and arc42
These two get compared as if you had to pick one. You do not: arc42 is the shape of the document, C4 is what goes in the picture. Teams that understand that use both and stop arguing.
Comparison
Structurizr, and when to use something else
Structurizr is the reference implementation of C4, written by the person who invented C4. That is a real argument in its favour and worth saying before any comparison starts.
Practice
C4 with PlantUML: diagrams as text
Text-based diagrams review like code, diff like code and survive like code. Here is how PlantUML fits a C4 model — and where writing everything by hand stops paying.
Comparison
C4 tools compared
Drawing tools, diagrams-as-code and modelling tools solve different halves of the problem. The right choice depends on whether you are producing pictures or maintaining a model — and on whether the model has to stay on your own machine.
See it as a model rather than a picture
Viaduct puts all four levels in one navigable model with the documentation attached. It runs locally in the browser — no account needed.