UML component diagrams

A component diagram describes a system as replaceable parts. A component in UML is not just any class - it is a unit with a defined boundary that could, in principle, be swapped for a different implementation of the same contracts without anything around it noticing.

That definition is the whole value. The diagram forces you to write down, for every part, exactly two things: what it provides and what it requires. Those two lists are the part's contract with the rest of the system, and they are the thing you actually need when planning a migration, scoping a rewrite, or deciding whether a service boundary is in the right place.

The ball and socket form is the compact one and what most tools draw by default: a lollipop sticking out of a component is an interface it provides, a half-cup is one it requires, and a ball resting in a socket is the two wired together. It is the same information as the arrows above, in less space. Use whichever your readers find easier; be consistent within a diagram.

Every mark this diagram kind can carry - both interface notations, assembly and delegation connectors, ports, and the four stereotypes worth writing - is set out in component diagram symbols.

This is the question every first component diagram gets stuck on, and the spec is no help: UML says a component is a replaceable unit with a defined contract and leaves the size entirely to you. That is the right answer for a standard and a useless one at a whiteboard, so here is the working rule.

A component is whatever you could put out to tender.If you can imagine handing another team the provided and required interface lists and saying "build this, we will not look inside", it is a component. If handing that over would require a conversation about the internals, the boundary is drawn in the wrong place - and that is the finding, not a drawing problem to be worked around.

In practice that usually lands on one of these, and which one it lands on tells you what the diagram is for.

• A deployable service. One repository, one pipeline, one on-call rota. The most common answer in anything built in the last decade, and the level at which the diagram is worth keeping in the repository.
• A library or module. Inside one deployable, when the argument is about internal structure - which package may depend on which. Here a package diagram often says the same thing more cheaply.
• A whole system. The mainframe, the CRM, the payment provider. The level for a context diagram, where the point is what you depend on rather than how any of it is built.

Mixing two of those levels on one diagram is the mistake that produces the sprawling component diagrams people remember. A picture with three microservices, a utility library and "SAP" on it is three diagrams overlaid, and no reader can tell which boxes are peers.

The single most useful reading technique is to cover a component with your hand. What is left is its contract: the interfaces that were attached to it. If you can hand that list to another team and say "build something that satisfies this", the diagram is doing its job. If you cannot - if replacing the component would require knowing things not drawn - the boundary is in the wrong place, and that is worth knowing before somebody tries.

The second technique is to follow the required interfaces. Every one is a dependency somebody has to satisfy, and a cycle in that graph is a genuine architectural problem that a component diagram makes visible immediately.

Both techniques are easier to see applied than described. Five diagrams of systems you have probably worked on - a shared catalogue, ports and adapters, a legacy swap, a plugin host and a cycle - are worked through in component diagram examples, each with the argument it settles.

Five diagram kinds are rectangles connected by lines, and the difference between them is entirely what a rectangle is. Picking the wrong one is the most expensive mistake available here, because the diagram will look fine and answer a question nobody asked.

The question that comes up most is component versus deployment, and the split is clean once stated: a component is a logical unit and a node is a physical one. One component can run on forty nodes; one node can host a dozen components. The moment a box on your component diagram acquires a region, an instance count or a hostname, it has stopped being a component and the diagram has quietly become two.

If you have met C4, its containerdiagram sits almost exactly where a component diagram at the deployable-service level does, and its own "component" level is a step further in than UML usually means. The vocabularies do not line up, so say which one you are using on the diagram itself - that one line of legend prevents most of the arguments.

Component diagrams age well, which is unusual. Interfaces change far more slowly than the code behind them, so a component diagram checked into a repository stays true for much longer than a class diagram of the same system - and is correspondingly more worth maintaining.

1. Components that are really classes. If it cannot plausibly be replaced independently, it is not a component. Use a class diagram.
2. Only provided interfaces drawn. The required ones carry the dependency information, which is the more useful half.
3. Arrows between components with no interface.A bare arrow says "depends somehow", which is the thing this diagram exists to make precise.
4. Mixing in deployment. Servers, regions and containers belong on a deployment diagram.
5. Interfaces named after the provider. ILedger is fine when there is one ledger; when there might be two implementations, name the contract after the capability, not the current supplier.