Sequence Diagram: UML Notation, Fragments and 3 Examples
November 11, 2026 · 16 min read
Sequence Diagram Guide: UML Notation, Fragments and 3 Examples
A sequence diagram shows how the parts of a system talk to each other over time. Each participant gets a vertical lifeline, and every message is an arrow between lifelines, read from top to bottom. This guide covers the UML notation and fragments, then builds three complete examples you can copy as plain text.
What Is a Sequence Diagram?
In UML, it's one of four interaction diagrams. The participants sit in a row across the top, a dashed lifeline drops below each one, and messages run between them as horizontal arrows. Time flows downward, so the first call is at the top and the last reply is at the bottom.
A good diagram covers one scenario: a single path through a single use case, such as a member signing in with the wrong password. That focus keeps it readable. When you need the success path and the failure path, you either draw two diagrams or wrap the difference in a fragment, which you'll see below.
A system sequence diagram is a narrower kind that treats the whole system as one black box and shows only what the actors send it and get back. Both use the notation from the UML 2.5.1 specification, which the Object Management Group published in December 2017 and which is still the current version.
Why Do We Make a Sequence Diagram?
You make one when the order of calls matters more than the structure of the code. Typical reasons:
- Designing an API interaction before you build it. Who calls whom, in which order, and what comes back. Arguing about arrows is cheaper than rewriting handlers.
- Documenting a flow that's hard to follow in code. Sign-in, payment and webhook handling jump across several services, and a picture of one request beats a tour of five repositories.
- Reviewing a design. A chatty integration shows up as a ladder of arrows. A missing error path shows up as an
altblock with noelse. - Onboarding. One diagram near the top of a README tells a new engineer how a request moves through the system.
It's the wrong tool for showing structure (that's a class diagram) or every branch of a business process (that's an activity diagram). It answers one question well: what happens, in what order, between whom.
UML Sequence Diagram Notation: Lifelines, Messages and Activations
You need about nine symbols to read almost any UML sequence diagram. The table maps each element to its UML shape and to the Mermaid text that draws it, because every example here is built as text.
| Element | UML symbol | What it means | Text that draws it |
|---|---|---|---|
| Lifeline | Box with a dashed line below it | A service, object or component taking part | participant W as Reports App |
| Actor | Stick figure with a lifeline | A person or outside system that starts things | actor U as User |
| Synchronous message | Solid line, filled arrowhead | The caller waits for an answer | U->>W: Export report |
| Asynchronous message | Solid line, open arrowhead | The sender carries on without waiting | W-)L: Record export |
| Reply | Dashed line, open or filled arrowhead | The return from a synchronous call | J-->>W: File ready |
| Create message | Dashed line, open arrowhead, ending at a new box | A participant comes into existence mid-flow | create participant J as Export Job |
| Destruction | An X at the bottom of the lifeline | The participant stops existing | destroy J before its last message |
| Execution specification | Thin rectangle on the lifeline | The participant is busy handling a call | activate W and deactivate W, or + and - on arrows |
| Note | Rectangle with a folded corner | A comment attached to one or more lifelines | Note over U,W: Text |
The execution specification is what most people call an activation bar. Mermaid's arrows map closely onto UML: ->> is a solid line with a filled head, -) has an open head, and -->> gives the dashed reply. For a create message, --) draws the dashed line with an open arrowhead that UML asks for. If you write PlantUML, our PlantUML sequence diagram syntax guide lists its arrows beside these Mermaid ones.
Here's every row from the table in one short diagram. Copy the whole block, fences included:
```mermaid
sequenceDiagram
actor U as User
participant W as Reports App
participant L as Audit Log
U->>+W: Export report
create participant J as Export Job
W--)J: Start
W-)L: Record export
J-->>W: File ready
destroy J
W-xJ: Dispose
W-->>-U: Download link
Note over U,W: The user waits for one reply
```
It draws a stick figure for the user and boxes for the reports app and the audit log. The Export Job box appears partway down, level with the arrow that creates it, and its lifeline stops at the dispose arrow. A thin activation bar covers the reports app from the first request to the download link, because the + and - suffixes open and close it.
Combined Fragments: alt, opt, loop, par, break and critical
A combined fragment is a rectangle drawn around a group of messages, with an operator in a small pentagon at its top-left corner. Each section inside it (an operand) can carry a guard in square brackets, such as [password matches] or [else]. If you leave the guard out, UML treats it as true.
| Operator | Meaning | Typical guard | Mermaid keyword |
|---|---|---|---|
alt | Pick exactly one of several branches | [valid], then [else] | alt, else, end |
opt | Run the block once or skip it | [coupon entered] | opt |
loop | Repeat the block | loop(1,3) or [more pages] | loop |
par | Run the branches in parallel | none needed | par, and |
break | Run this block, then abandon the rest of the enclosing fragment | [timeout] | break |
critical | Treat the block as atomic, so nothing interleaves with it | none needed | critical (Mermaid adds option branches) |
A loop fragment takes optional bounds: loop(1,3) means at least once and at most three times, and a bare loop means zero to unlimited. Mermaid has no syntax for those bounds, so you write the condition as the loop's label instead. It prints every fragment label in square brackets, so the label reads like a UML guard.
UML 2.5.1 defines six more operators: seq, strict, neg, assert, ignore and consider. They're rare outside formal modelling, and Mermaid has no keyword for any of them. The combined fragment reference on uml-diagrams.org shows how each one is drawn.
Here's a loop with an alt nested inside it:
```mermaid
sequenceDiagram
participant C as Client
participant S as Search API
loop For each page of results
C->>S: GET next page
alt More results
S-->>C: 50 items
else No results left
S-->>C: Empty list
end
end
```
The renderer draws a frame labelled loop around both messages and a second frame labelled alt inside it. A dashed divider splits the alt frame into its two branches, each with its own label.
Sequence Diagram Example 1: Sign-In With a Rate Limit and Lockout
The first worked example is a sign-in that checks a rate limiter before it ever looks at the password. It uses a break for the lockout and an alt for the right and wrong password.
```mermaid
sequenceDiagram
actor M as Member
participant P as Sign-in Page
participant A as Auth Service
participant R as Rate Limiter
participant C as Credential Store
M->>P: Submit email and password
P->>A: POST /sessions
activate A
A->>+R: Count recent failures
R-->>-A: 5 in the last 15 minutes
break Five or more failures
A-->>P: 429 Too Many Requests
P-->>M: Account locked, try later
end
A->>+C: Fetch password hash
C-->>-A: Hash and salt
alt Password matches
A->>R: Reset failure count
A-->>P: 201 Created with session cookie
P-->>M: Show dashboard
else Password wrong
A->>R: Add one failure
A-->>P: 401 Unauthorized
P-->>M: Show error, keep email filled in
end
deactivate A
```
Read it message by message:
- The member submits the form, and the page posts it to the auth service, which activates and stays busy until the end.
- The auth service asks the rate limiter how many recent failures this email has. The short activation bar on the limiter shows a quick, synchronous lookup.
- The
breakfragment says that when the guard holds, the service answers 429 and skips everything below it. Nothing after the frame runs on that path. - Otherwise it fetches the stored hash, and the
altsplits on the comparison. A match resets the counter and returns a session cookie. A mismatch adds a failure and returns 401.
Notice that both branches reply to the page. A branch that ends without a reply is usually a bug in the design, not just in the drawing.
Sequence Diagram Example 2: API Request With Retries and a Timeout
The second example mixes synchronous and asynchronous messages. A mobile app places an order through a gateway, and the gateway retries the orders service up to three times.
```mermaid
sequenceDiagram
participant M as Mobile App
participant G as API Gateway
participant O as Orders Service
participant Q as Event Queue
M->>+G: POST /orders with Idempotency-Key
loop At most 3 attempts, until a 201
G->>+O: createOrder
alt Order saved
O-)Q: OrderPlaced event
O-->>G: 201 Created
else No reply within 2 seconds
G->>G: Back off, then retry
end
deactivate O
end
break All 3 attempts timed out
G-->>M: 504 Gateway Timeout
end
G-->>-M: 201 with order ID
```
What each part tells you:
- The app's request is synchronous, so the gateway's activation bar runs from the first arrow to the final reply.
- The loop label carries the guard. In strict UML you'd write it as
loop(1,3)plus a condition, but a readable label is clearer for most audiences. O-)Qhas an open arrowhead because the orders service publishes the event and moves on. It doesn't wait for whoever consumes the queue.- The
elsebranch has no reply arrow at all. That's the point: a timeout is the absence of a message, and the self-message on the gateway shows the back-off. - The idempotency key in the first request is what makes retries safe. Without it, a slow first attempt and a fast second one could both create an order.
Here's a trimmed version you can edit. The preview redraws as you type:
Sequence Diagram Example 3: Checkout With Stock Checks, a Coupon and Payment
The third example uses three fragments at once and creates a participant halfway down. A buyer checks out a cart, every line item is reserved, a coupon may apply, and the card is either approved or declined.
```mermaid
sequenceDiagram
actor B as Buyer
participant C as Cart Service
participant I as Inventory
participant P as Payment Provider
participant E as Email Service
B->>+C: Check out cart
loop Each line item
C->>I: Reserve SKU and quantity
I-->>C: Reserved
end
opt Coupon code entered
C->>C: Apply discount
end
C->>+P: Charge card for total
P-->>-C: Authorization result
alt Card approved
create participant O as Order
C--)O: new Order(items, total)
C-)E: Email the receipt
C-->>B: Order confirmation
else Card declined
C->>I: Release reservations
C-->>B: Payment failed, try another card
end
deactivate C
```
How to read it:
- The
looprepeats the reservation once per line item. One frame replaces what would otherwise be a long column of identical arrows. - The
optblock applies a discount only when the buyer typed a code. It has one operand and noelse, which is exactly what separatesoptfromalt. - The payment call is synchronous, so the provider gets a short activation bar.
- In the approved branch, the Order lifeline starts at its create message. The receipt goes out asynchronously because checkout shouldn't wait for an email server.
- The declined branch releases the stock reserved earlier. Spotting that cleanup step is the kind of thing a diagram review catches before the code does.
How Do You Draw a Sequence Diagram in Six Steps?
These steps work the same whether you sketch on a whiteboard or type text:
- Pick one scenario. Name it in a sentence, such as buyer checks out with a declined card.
- List the participants in the order they're first called, left to right. Put the actor that starts the flow on the far left.
- Write the happy path as messages from top to bottom, then add a reply for each synchronous call.
- Mark who's busy with activation bars, mainly on the services that do real work.
- Wrap branches and repeats in
alt,opt,looporbreak, each with a guard. - Check it against the code or the API spec. A diagram that disagrees with the system is worse than none.
To draw it as text, put the diagram inside a fenced block tagged mermaid. If fences are new to you, our guide to Markdown code blocks covers them, and Mermaid diagrams in Markdown explains which platforms render the fence.
GitHub draws it in READMEs, issues and pull requests, per GitHub's diagram docs. Add autonumber on the line after sequenceDiagram to number every arrow. The full keyword list is in the Mermaid sequence diagram syntax.
Paste any example from this page into our free online editor and the preview on the right renders the diagram while you type, with no account needed. When you need an image for a slide or a wiki, the Mermaid editor adds sample templates, theme selection and PNG or SVG export.
We prefer one scenario per diagram over a single drawing with four nested alt frames. Two short diagrams get read, and one giant one gets skimmed.
Text has a real limitation, though: Mermaid places every lifeline and arrow for you, so you can't drag a box closer or shorten a crossing arrow. It also has no syntax for six of UML's twelve operators, so strict UML coursework may still need a modelling tool. Our comparison of sequence diagram generator tools covers drag-and-drop options such as draw.io.
Is UML Still Used Anymore?
Yes, though not in the way it was once pitched. Few teams keep a complete UML model of their system and generate code from it. Plenty of teams that never draw a class diagram still put sequence diagrams in design docs, RFCs, API guides and READMEs.
What changed is the medium. A sequence diagram in UML used to live inside a modelling tool's project file. Today it often sits as text next to the code it describes, so it changes in the same review. The notation itself is stable: UML 2.5.1 has been the current version since 2017, and the symbols in the table above haven't changed in that time.
A sequence diagram earns its place when it shows one scenario clearly: the right participants, every reply, and fragments only where the flow really branches or repeats. Start from one of the three examples above, rename the participants to match your system, and add the error path you're worried about. When it's ready, open the Mermaid editor to pick a theme and export it as a PNG or SVG.