Sequence Diagrams
Showing the order of interactions over time — the only common diagram that makes latency, ordering and failure behaviour visible.
Definition
Participants across the top, time running down, messages between them. It answers what happens in what order, which a static diagram cannot.
What it is uniquely good at
- Making round trips visible. Eight sequential calls look innocuous in a component diagram and are obviously a latency problem in a sequence diagram.
- Exposing hidden coupling. A flow requiring six services to be available to complete is immediately apparent.
- Documenting failure paths, which is where most of the value is and where most sequence diagrams stop.
- Communicating an asynchronous flow, where the ordering is genuinely non-obvious.
The rule that makes them worth drawing
Draw the failure sequences, not just the happy path.
A happy-path sequence diagram usually tells the reader what they already assumed. The valuable ones answer: what happens when the third call times out? Who retries? What is the user shown? What state is left behind?
Those questions have architectural answers, and drawing them is frequently how a design's missing compensation logic is discovered.
When to use them
Sparingly, and for the interactions that matter: the critical user journey, the distributed transaction with compensation, the asynchronous flow whose ordering is subtle. One or two per system.
Not for every endpoint — that is documentation the code expresses better and which will drift.
Failure scenarios
- Only the happy path, so the diagram documents the easy case.
- One per endpoint, producing a set nobody maintains.
- Too many participants, so the diagram is unreadable. Six is about the limit.
- No timing or timeout information on a diagram whose whole point is time.
- Drawn once during design and never checked against what was built.
Interview question
"What would you put on a sequence diagram that a component diagram cannot show?"