C4 vs UML
The comparison is asked as an either/or and it is not one: C4 says which diagrams to draw, UML says how to draw them, and the useful answer is usually both.
6 min readC4 model3 of 3
The short answer
- C4 is a convention about what to draw at four levels of zoom. UML is a notation with defined semantics. They answer different questions.
- A C4 container diagram drawn with UML component notation is simultaneously a correct C4 diagram and a legal UML one.
- Choose UML when the diagram has to be precise or exchanged between tools; choose plain C4 boxes when the audience includes people who do not read notation.
- The real failure is neither: it is a diagram whose boxes mean different things because nobody said which level or which notation it was.
01They are not the same kind of thing#
The comparison is usually framed as a choice, which is why it rarely produces a useful answer. One of the two is a convention about which diagrams a system should have; the other is a language with defined element and relationship semantics. Comparing them is closer to comparing a table of contents with a typeface than to comparing two notations.
| Element | Notation | What it means |
|---|---|---|
| C4 | Four levels, no prescribed shapes | Says what to draw at each zoom level and who it is for. Defines no element semantics, so there is nothing to get formally wrong. |
| UML 2.5.1 | Fourteen diagram types, defined shapes | Says how to draw a structure or a behaviour, with a metamodel that makes some diagrams legal and others invalid. Says nothing about which diagrams your system needs. |
That difference is also the reason the two compose rather than compete. C4 leaves the notation open; UML is a notation. Filling one gap with the other is the intended use of both.
02Drawing a C4 level in UML#
The mapping is direct enough that most teams do it without noticing. A context diagram is actors and external systems around a subject boundary, which is exactly a use case diagram's frame. A container diagram is UML components with interfaces between them. A component diagram is the same notation one level down.
The payoff for using a real notation is not aesthetic. A UML model exports to XMI and can be checked for legality; a set of rectangles cannot be either. If the diagram is going to be handed to another team, another tool, or an auditor, that matters. If it is going on a wiki page for people who will never open a modelling tool, it does not.
03What each one leaves out#
C4 is entirely about static structure. There is no C4 diagram for a sequence of messages, a state machine or a business process - so a system documented only in C4 has four pictures of what exists and none of what happens. That is the gap UML's behaviour diagrams fill, and it is a real one: most incidents are about behaviour.
UML's gap is the opposite. It gives you fourteen diagram types and no guidance about which of them your system needs, which is how teams end up with a class diagram of everything and no picture of the system as a whole. Choosing a diagram is a real skill precisely because the specification does not help with it. C4's four levels are a ready-made answer for the structural half.
In one line each
- 01C4 decides which diagrams exist; UML decides what the shapes on them mean.
- 02A container diagram in UML component notation is correct in both at once.
- 03Use UML where precision or tool exchange matters, plain boxes where the audience does not read notation.
- 04C4 has no behaviour diagrams and UML has no opinion about scope - which is why most teams end up using both.
04Common questions#
Is C4 better than UML?
The question does not resolve, because they are not the same kind of thing. C4 prescribes four diagrams and what belongs on each; UML prescribes shapes and their meanings. You can follow C4 and draw it in UML, follow C4 and draw it in plain boxes, or use UML with no C4 structure at all.
Can I draw a C4 diagram in UML?
Yes, and it is often the better choice. A container diagram maps cleanly onto UML components with interfaces; a context diagram maps onto actors and a subject boundary. The result is legal UML and correct C4 at the same time, and it exports to XMI, which plain boxes never will.
Does C4 replace the UML diagram types?
No. C4 covers static structure at four zoom levels and says nothing about behaviour. Sequence, state machine and activity diagrams have no C4 equivalent, so a system documented only in C4 has no description of how anything actually happens over time.
Which should a new team start with?
C4's levels 1 and 2, drawn in whatever they can already read. The value in the first month is agreeing on what the system consists of, and a notation argument at that point costs more than it returns. Add UML precision where a diagram turns out to need it.
In this series
- 01What is C4?
- 02Container diagram
- 03C4 vs UML
Related reading
Foundations
Structure diagrams
Foundations
Foundations
Modelling practice