UML component diagrams
The system as a set of replaceable parts and the contracts between them. What each piece offers, what it needs, and - the useful bit - what you would have to honour to swap one out.
8 min readUML 2.5.17 of 15
01What it shows
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.
02The notation
| Element | Notation | What it means |
|---|---|---|
| Component | rectangle with the plug icon | A replaceable unit. The icon in the corner is the UML 2 form; the older form put the icon in place of the box. |
| Provided interface | The component implements this contract. Drawn as a realization to an «interface», or as a ball on a stick. | |
| Required interface | The component needs somebody to provide this. Drawn as a dependency, or as a socket - a half-cup on a stick. | |
| Assembly connector | a ball sitting in a socket | One component's provided interface wired to another's required one. The compact form of the two rows above. |
| Port | small square on the boundary | A named interaction point. Use when one component has several distinct channels - a public API and an admin API, say. |
| Delegation connector | From a port on the outside to a part on the inside: this external contract is actually handled by that internal piece. |
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.
03Reading one properly
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.
04When to draw one
Reach for it when
- Defining service boundaries before splitting or merging systems
- Documenting what a team owns and what it depends on from others
- Planning a replacement - the contract is exactly what the new thing must satisfy
- Reviewing whether dependencies flow the way the architecture claims they do
Reach for something else when
- You mean physical machines and processes - use a deployment diagram
- You mean the internals of one component - use a composite structure diagram
- The parts are classes, not replaceable units - use a class diagram
- There are three services and everyone already knows how they connect
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.
05Common mistakes
- Components that are really classes. If it cannot plausibly be replaced independently, it is not a component. Use a class diagram.
- Only provided interfaces drawn. The required ones carry the dependency information, which is the more useful half.
- Arrows between components with no interface.A bare arrow says "depends somehow", which is the thing this diagram exists to make precise.
- Mixing in deployment. Servers, regions and containers belong on a deployment diagram.
- Interfaces named after the provider.
ILedgeris fine when there is one ledger; when there might be two implementations, name the contract after the capability, not the current supplier.
In one line each
- 01A component is a replaceable unit with a defined contract, not just a big class.
- 02Every component has two lists: what it provides and what it requires.
- 03Realization (hollow triangle, dashed) points at the interface being implemented.
- 04Dependency (open arrow, dashed) points at the interface being required.
- 05Ball-and-socket is the compact form of the same information.
- 06Cover a component with your hand: what remains is what a replacement must satisfy.
Related reading