Skip to content
← All principles

The user experiences your boundaries, not your diagram

Architecture diagrams describe a system to its makers. Users encounter only the seams, and every seam is a promise.

Principle 3 of 11
The architecture sits faint behind, the makers’ blueprint. The one bold line is the seam the user actually meets, and where state crosses it.

A clean architecture diagram is a useful thing for the people building a system. It is invisible to the people using it. What a user actually meets is the seams: the places where one system hands off to another, where state crosses a line, where authority changes hands.

Don Norman named the gap this opens. The user never sees your model, only the system image your seams project, and they build their own model from that. And every seam is a commitment. A boundary is a promise; a boundary no one trusts is not a boundary at all, but a wall with a door someone forgot to lock.

Design the seams as carefully as you design the components. That is the surface where the product is kept, or quietly broken.