A sequence diagram is about order, not structure.
Time runs down the page. That single convention is what the diagram is for.
A sequence diagram shows how participants exchange messages over time. Participants run along the top, each with a vertical lifeline descending from it, and time runs downward. Arrows between lifelines are messages, and the bars drawn on a lifeline show when that participant is actively processing. It is the right diagram when the ordering of interactions is the thing you need to reason about: an authentication handshake, a checkout, a retry path. It is the wrong diagram for showing what a system is made of.
What the notation actually encodes
A solid arrow is a synchronous call, a dashed arrow is a return, and an open arrowhead conventionally marks an asynchronous message. The activation bar shows a participant is doing work rather than waiting. Combined fragments wrap regions in alt, opt, loop or par to express branching, optionality, repetition and concurrency. Most real diagrams use a fraction of this and are perfectly readable.
The failure mode is length
Sequence diagrams get unreadable long before they get complicated. Past roughly a dozen messages the eye cannot follow a lifeline down the page, and the usual cause is that the diagram is covering several scenarios at once. The fix is almost always to split it: one diagram for the happy path, one for the interesting failure, rather than one diagram with four nested alt fragments.
When you want a different diagram
If the question is what components exist and how they connect, a container or context diagram answers it and a sequence diagram does not. If the question is what states something moves through, a state diagram is the right shape. Sequence diagrams answer questions about order, and using one for a structural question produces a diagram that technically contains the answer and hides it.
Where they earn their keep
Protocol handshakes, anything with a callback or a webhook, distributed transactions and retry or timeout behaviour. These are the cases where the interesting information is entirely in the ordering and the interleaving, and no structural diagram can show it. They are also the cases people get wrong in prose, which is the real argument for drawing one.
Questions
Related
- What Is Spec-Driven Development?Review the plan, not the pull request. The plan is a page; the pull request is a thousand lines.
- What Is a Container Diagram?The most useful diagram most teams do not have, and the worst-named one in the field.
- What Is a System Context Diagram?One box for everything you own. The value is entirely in what surrounds it.
- What Is a Component Diagram?Useful for the one container that is genuinely complicated. Drawn far more often than that.
Last updated