Sequence Diagram: What It Is, Its Notation, and How to Build One

A sequence diagram answers one question that no other notation answers well: who talks to whom, in what order. Not what the system contains, not who owns it — the order of the conversation. If the bug you are explaining is a timing bug, this is the only diagram that will show it.

Live interactive diagramUse the player controls to follow the steps

The TLS 1.3 handshakePlaying silently in this guideWatch with narrationOpen in editor

What a sequence diagram actually is

It is a UML behavioural diagram: participants across the top, time running downward, messages as arrows between them. Time is the vertical axis, and that single convention is what makes it readable — anything lower on the page happens later.

It came out of Ivar Jacobson's object-oriented work in the 1980s and was folded into UML in 1997. Thirty years on it is still the default for describing protocols, because a protocol is an ordered exchange and nothing else captures order so cheaply.

If the order does not matter, you do not need a sequence diagram. Order is the entire reason this notation exists.

The parts, and what each one promises

• Participant — a box across the top. A person, a service, a database, a queue. Name it for its role, not its hostname.
• Lifeline — the dashed vertical line below each participant. It represents that participant existing through time.
• Message (solid arrow) — a call, request or event travelling from one lifeline to another. Label it with what is being asked, not how.
• Reply (dashed arrow) — the response coming back. Drawing replies is optional and usually worth it: a diagram of only requests hides where the waiting happens.
• Activation bar — the narrow box on a lifeline showing that participant is busy. This is where latency lives, and the reason a reader can see a slow call.
• Self-message — an arrow that loops back to its own lifeline: internal work worth naming.

Order the participants left to right in the order they first act. A diagram whose arrows travel consistently rightward reads in one pass; one whose arrows zig-zag makes the reader re-find the thread on every line.

Why draw one at all

• It makes latency visible. Activation bars show who is waiting on whom. A performance conversation with a sequence diagram on the table is a different conversation.
• It settles integration arguments. Two teams agreeing on “we call your API” can still disagree on who retries, who times out and who is authoritative. Drawn, that disagreement is one arrow in the wrong place.
• It is the fastest way to onboard someone onto a flow. Login, checkout, settlement — a new engineer reads the exchange in a minute instead of tracing it through four repositories.

When to reach for one — and when not to

• You care about structure, not order → an architecture diagram or C4 model.
• The branching is the interesting part → a flowchart. See building a clear flowchart.
• The argument is about which team owns a step → a swimlane, and ownership and handoffs.
• The thing has states rather than exchanges — draft, active, expired → a state machine.
• You are describing data at rest and its relationships → an ER diagram.

Who actually draws these

• Backend and platform engineers — API contracts, retries, idempotency, and the exact path of a production incident.
• Security engineers — authentication and key exchange, where the order of steps is the security property.
• Integration and solution architects — the hand-offs between systems that no single team owns.
• Payments, fintech and operations — settlement flows that unfold over days, where timing is the business rule.
• Support and SRE — escalation and recovery paths, drawn once so nobody improvises at 2am.

Examples you can open and edit

Protocols, payments, retail operations and manufacturing. Open one, rename the participants, and the shape of your own exchange is already there.

Building one in Diagramium

1. List the participants first, in the order they act. Getting this order right removes most crossing arrows before you draw one.
2. Type it instead of dragging. The sequence editor has a text tab: User->API: Sign in on one line draws the arrow. Canvas and text stay in sync, so a designer can drag while an engineer types.
3. Draw the happy path end to end before adding a single failure branch.
4. Add the replies that matter. Not every one — the ones where the caller waits.
5. Put the contract in a step note: timeout, retry policy, idempotency key. Notes travel inside the document rather than living in a ticket.
6. Press Present. The exchange plays one message at a time, which is exactly how you want to explain a protocol to someone who has never seen it.
7. Export as SVG for the design doc, or embed the interactive player in an internal page so it cannot go stale in an attachment.

Design decisions that separate a good one from a mess

• Six participants or fewer. Past that the arrows dominate and the story disappears. Split by phase instead.
• One direction of travel. Order participants so the flow trends rightward and downward.
• Name messages for intent — “Reserve stock”, not “POST /v2/inventory”. The endpoint belongs in a note.
• Colour only the exceptional path. Timeouts and rollbacks, nothing else.
• Keep failure branches on the same diagram when they are short. A separate “error cases” diagram gets read by nobody.

Common mistakes

• Drawing the architecture instead of the exchange. If there are no arrows between lifelines in time order, you wanted an architecture diagram.
• Every participant is a microservice. Include the human and the third party — they are usually where the delay is.
• No replies anywhere. The diagram then implies fire-and-forget, and readers will design against that.
• Endpoint names as labels. They date fast and they hide the intent.
• Omitting the timeout path. The interesting failure in a distributed exchange is almost always “no answer came back”.

The checklist

Run this before you share it.

1. Participants are named for roles, and ordered by first action.
2. Time genuinely runs downward — nothing later appears higher.
3. Replies are shown wherever a caller waits.
4. Messages describe intent, not endpoints.
5. The timeout or failure path is on the diagram.
6. Six participants or fewer, or split by phase.
7. You can narrate the exchange in Present without stopping.
8. Contract details live in step notes, not in the labels.