UML Sequence Diagrams: A Complete Guide
Sequence diagrams show how objects collaborate over time by exchanging messages. This guide covers lifelines, message types, activation, and the fragments that model real control flow.
A sequence diagram answers a question that class diagrams cannot: not what the objects are, but how they talk to each other to get something done. It reads top to bottom as time and left to right as participants, so a login flow, a checkout, or an API call becomes a visible conversation. For anyone trying to understand a runtime interaction, a sequence diagram is often clearer than the code itself, because it collapses many files into one ordered story.
This guide covers the building blocks in the order you will use them: lifelines and participants, the message arrows and what each style means, activation bars, and the combined fragments that let you express loops, conditions, and parallel branches. You can draw these interactively at /diagrams, write them as text in the Mermaid editor at /diagram-tools/mermaid-editor, or read the focused reference at /diagram-tools/sequence-diagram.
Lifelines and participants
Every participant in the interaction gets a box at the top of the diagram with a vertical dashed line dropping down from it: the lifeline. The box is typically named for an object or a role, such as ":OrderService" or "user: Customer". The lifeline represents that participant's existence through the time span of the interaction, and everything that happens to it is read down its line.
Participants are usually objects, but they can also be actors (a human user, drawn as a stick figure), external systems, or boundary and control objects if you are following a layered convention. Order them left to right in the rough order they enter the interaction, with the initiator on the far left. A well-ordered set of lifelines makes the diagram read like a sentence.
Messages and their arrow styles
Messages are horizontal arrows from one lifeline to another, and the arrow style carries meaning. A solid line with a solid filled arrowhead is a synchronous call: the sender waits for the receiver to finish. A solid line with an open arrowhead is an asynchronous message: the sender fires it and continues without waiting, common in event-driven and messaging systems. A dashed line with an open arrowhead is a return, showing the value or control coming back to the caller.
Two special messages are worth knowing. A message a lifeline sends to itself loops back to the same line and is drawn as a self-call, useful for showing internal work. Creation of a new object is a message that lands on a participant box positioned partway down the diagram rather than at the top, and destruction is marked with a large X at the bottom of a lifeline. Labeling messages well, with the method name and key arguments, is what makes the diagram legible.
Activation bars and focus of control
The thin vertical rectangles overlaid on a lifeline are activation bars, also called execution occurrences. They show when a participant is actively doing work, from the moment it receives a call until it returns. Nested activations, drawn as slightly offset overlapping bars, show a method calling another method on the same object before the first returns.
Activation bars are optional in quick sketches but they add real clarity in interactions with a lot of nesting, because they make the call stack visible. When you can see that ServiceA is still active while it waits on ServiceB which is waiting on the database, the shape of the latency and the blocking becomes obvious in a way that prose describing the same flow never manages.
Combined fragments: loops, conditions, and parallelism
Real interactions are not straight lines; they branch, repeat, and run concurrently. UML handles this with combined fragments, rectangular regions with a label in the top-left corner. The label, called an interaction operator, states what kind of control flow the box represents.
- alt. Alternatives, like an if/else: separate regions guarded by conditions, only one of which executes.
- opt. An optional fragment that executes only if its guard is true, equivalent to an if with no else.
- loop. A repeated fragment, with the iteration bounds or condition in the label, such as loop [for each item].
- par. Parallel regions that execute concurrently, useful for fan-out to multiple services.
- break. An exceptional exit from the enclosing interaction, like an early return on error.
- critical. A region that must execute atomically without interleaving, for modeling locks or transactions.
- ref. A reference to another sequence diagram, letting you decompose a large interaction into named pieces.
Drawing sequence diagrams efficiently
Sequence diagrams are one of the best candidates for a text-based workflow, because their structure is inherently linear. In Mermaid you write "A->>B: request" and "B-->>A: response" and the renderer lays out the lifelines and arrows for you, which is far faster than dragging arrows by hand when the interaction is long. The Mermaid editor at /diagram-tools/mermaid-editor supports this and versions cleanly in Git.
For diagrams you want to polish visually or hand to a stakeholder, a canvas is better, and describing the flow in plain English to the AI generator at /diagram-tools/ai-diagram-generator gives you a first pass to refine. Whichever route you take, keep each diagram to one scenario. A sequence diagram that tries to show the happy path, three error cases, and two edge conditions at once becomes unreadable; draw the happy path clearly and give the important error cases their own smaller diagrams.