C4 level 3, and why it is usually the wrong diagram.
Useful for the one container that is genuinely complicated. Drawn far more often than that.
A component diagram is C4 level 3. It takes one container from level 2 and shows the major structural building blocks inside it, their responsibilities and how they interact. It is genuinely useful for a container complex enough that its internal structure is a live question. It is also the level that goes stale soonest of the three worth drawing, because internal structure changes with ordinary refactoring, and it is the one teams most often draw for containers that did not need it.
The test for whether you need one
Ask whether anyone is confused about how this container is organised. If the answer is no, a component diagram documents something nobody was asking about and then goes stale. If a container has grown to where new engineers consistently put code in the wrong place, that is the container that needs one, and usually only that one.
Component does not mean class
A component is a grouping of related functionality behind a clear interface, not a single class and not a source file. Once a component diagram is showing individual classes it has slid into level 4, where maintenance stops being viable, and it will be wrong within a sprint.
The maintenance problem, stated plainly
Level 1 changes when the business changes. Level 2 changes when the deployment topology changes. Level 3 changes when someone refactors, which is to say constantly. This is why the common advice is to generate level 3 on demand rather than maintain it, and to keep hand-drawn effort at levels 1 and 2.
What often works better
For most containers, an architecture decision record explaining why the internal structure is the way it is outlasts a diagram showing what it currently is. The reasoning stays true across refactors; the picture does not. If you only have appetite for one artefact, the record is usually the better bet.
Questions
Related
- What Is Agentic Coding?The difference is the feedback loop. An agent can find out it was wrong.
- What Is the C4 Model?Four levels of zoom on one system. Two of them get maintained; the other two usually do not.
- What Is an Architecture Decision Record?The code shows what was decided. Only the record shows what was rejected, and why.
- What Is Architecture Drift?Nobody decides to let the diagram go stale. It goes stale because nothing in the process notices.
Last updated