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.
What it is for
A Component diagram zooms into exactly one container and shows the groupings of code inside it — a controller, a domain service, a repository, an adapter to an external system — with responsibilities and the dependencies between them.
Its audience is narrower than Level 1 or 2: it is for the engineers who work in that container, and for the reviewer trying to work out where a change belongs.
Choosing component boundaries
A component is a grouping of related functionality behind a clean interface, running inside the container process. In practice the boundary usually follows a capability rather than a layer: "Payment authorisation" is a better component than "Service layer".
- Name by responsibility — "Fraud check", "Statement generator", "Mainframe adapter".
- One line of purpose — If it takes a paragraph, it is probably two components.
- Show the technology when it matters — Spring MVC controller, Kafka consumer, cron entry point.
- Include the boundary crossings — The components that talk to databases and external systems are the ones readers came for.
A worked example
When Level 3 is worth it — and when it is not
Component diagrams have the worst maintenance ratio in C4: they change most often and are read least often. That is not an argument against drawing them, it is an argument against drawing them everywhere.
Draw one when a container is large enough that people repeatedly get lost in it, when you are onboarding several engineers into the same codebase, or when you are planning to split a container and need to see the seams. Skip it for containers whose structure is obvious from the folder tree.
A useful signal
If you cannot draw the Component diagram from memory after working in a container for a month, that container needs the diagram — or needs splitting.
Failure modes
- Layer diagrams — Controller → Service → Repository, three boxes, no information.
- Class diagrams in disguise — If the boxes are individual classes, you are at Level 4.
- Drawn once, never opened — A Level 3 diagram that lives away from the code will be wrong within a quarter.
Frequently asked
How is a component different from a microservice?
A microservice is deployed independently, which makes it a container in C4 terms. A component runs inside a container, in the same process, and ships with it.
How many components should one diagram show?
Roughly five to fifteen. Fewer and the diagram is not telling you anything the code does not; more and the container is a candidate for splitting.
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.