How to draw a component diagram

Before drawing anything, write a list. Not of your modules, not of your folders - of the parts of the system that could plausibly be swapped for a different implementation: bought instead of built, rewritten by another team, or run by somebody else.

That question is the whole filter. A folder is not a component and neither is a class; a thing with a boundary somebody could hand to a supplier is. The reporting system in this article produced four: a dashboard, a scheduler that runs reports overnight, the report service itself, and an adapter that talks to the data warehouse.

Place the parts and resist connecting them. Drawing arrows now means drawing them between components, and a line from Dashboard straight to Report service says only "these two are involved somehow", which is the vagueness a component diagram exists to remove.

Layout is worth thirty seconds here: put consumers on one side and providers on the other. Every diagram in this series is drawn left to right, dependencies flowing one way, because a reader can then check the direction at a glance rather than by following each line.

For each box, ask what somebody outside it is allowed to rely on, and name that. IReports and IWarehouse here - one contract per capability, not one per consumer. Attach it with a realization: dashed line, hollow triangle, pointing at the interface.

This step is where the real design happens, and it is the step people skip. Naming a contract forces you to decide what is public, and the argument that follows - "is the CSV export part of IReports or not?" - is the argument worth having before two teams answer it differently in code.

Now the second half, and the half that carries the information: for each component, which contracts does it need? Draw a dependency - dashed line, open arrowhead - from the component to the interface it requires. The finished result is the diagram at the top of this article.

Two things become visible the moment those arrows land. The dashboard and the scheduler both point at IReports, so changing it is now visibly a change to two consumers. And the report service points at IWarehouse rather than at the adapter, so the adapter is replaceable without the service noticing - which is either what you intended or a discovery worth making now.

A component diagram is finished when it survives these. They take a minute and each one has caught a real problem more often than it has passed cleanly.

1. Cover a box with your hand. What is left - the interfaces that were attached to it - is the specification of its replacement. If a replacement would need to know something that is not on screen, the boundary is in the wrong place.
2. Follow the arrows for a cycle. Two components that require each other cannot be deployed, tested or replaced independently. See the last of the worked examples for what that looks like and how it gets broken.
3. Check every component has at least one interface. A box with nothing attached is either not a component or not relevant to this diagram.
4. Read the interface names aloud. If one is named after its current provider rather than its capability - IMainframeBilling rather than IBilling - the contract has the supplier baked into it, and the swap the diagram promises will not be as clean as it looks.

The right-hand column is not pedantry about diagram kinds. Every item on it makes the picture bigger without answering the question this diagram was drawn for, and each one gives the diagram a second reason to go out of date: a component diagram survives a re-platforming untouched, and the same drawing with two AWS regions on it does not.

With the drawing done, the reference for every mark on it is in component diagram symbols, and the wider case for when this diagram kind is worth the effort at all is in the component diagram guide.