A team adopts a layered diagram model and produces every level for every part of the system. What has gone wrong, and how should the model be used?

What has gone wrong

Completeness has been mistaken for value. Producing every level for every component creates an enormous artefact that is out of date before it is finished, expensive to maintain, and read by nobody — because readers cannot tell which parts matter.

The model is a vocabulary for choosing an altitude, not a checklist of deliverables.

How it should be used

Context, always. One diagram showing the system as a single box, its users, and the external systems it depends on. This is the cheapest diagram to make, the most stable, and the one that removes most basic questions from every subsequent conversation. Almost every architecture document should have exactly one.

Container level, usually. The deployable units and data stores, how they communicate, and what each is responsible for. This is the level at which most architectural conversations actually happen, and it is usually the most valuable single diagram.

Component level, selectively. Only for the parts where the internal structure is genuinely architecturally significant — a complex subsystem, an area under redesign, a component whose boundaries are contested. Producing it everywhere is where the effort goes and the value does not.

Code level, almost never. It ages with every commit and the code itself is a better source. Generate it on demand if needed.

The maintenance rule that matters

Diagrams age at the rate of the thing they describe. Context diagrams change yearly; container diagrams change per release; component diagrams change per sprint. Producing artefacts that change faster than you can maintain them guarantees they will be wrong, and a wrong diagram is worse than no diagram because it is used confidently.

That argues for a small number of diagrams at stable altitudes, plus generated or ad-hoc detail where it is needed.

The practical guidance

Diagrams as code, versioned with the system, so they are reviewed alongside the change that invalidates them. An owner and a review trigger for each. And a willingness to delete: a diagram nobody has opened in a year is maintenance cost with no benefit, and removing it is an improvement.