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 alt block with no else.
  • 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.

ElementUML symbolWhat it meansText that draws it
LifelineBox with a dashed line below itA service, object or component taking partparticipant W as Reports App
ActorStick figure with a lifelineA person or outside system that starts thingsactor U as User
Synchronous messageSolid line, filled arrowheadThe caller waits for an answerU->>W: Export report
Asynchronous messageSolid line, open arrowheadThe sender carries on without waitingW-)L: Record export
ReplyDashed line, open or filled arrowheadThe return from a synchronous callJ-->>W: File ready
Create messageDashed line, open arrowhead, ending at a new boxA participant comes into existence mid-flowcreate participant J as Export Job
DestructionAn X at the bottom of the lifelineThe participant stops existingdestroy J before its last message
Execution specificationThin rectangle on the lifelineThe participant is busy handling a callactivate W and deactivate W, or + and - on arrows
NoteRectangle with a folded cornerA comment attached to one or more lifelinesNote 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.

OperatorMeaningTypical guardMermaid keyword
altPick exactly one of several branches[valid], then [else]alt, else, end
optRun the block once or skip it[coupon entered]opt
loopRepeat the blockloop(1,3) or [more pages]loop
parRun the branches in parallelnone neededpar, and
breakRun this block, then abandon the rest of the enclosing fragment[timeout]break
criticalTreat the block as atomic, so nothing interleaves with itnone neededcritical (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:

  1. The member submits the form, and the page posts it to the auth service, which activates and stays busy until the end.
  2. 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.
  3. The break fragment says that when the guard holds, the service answers 429 and skips everything below it. Nothing after the frame runs on that path.
  4. Otherwise it fetches the stored hash, and the alt splits 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-)Q has an open arrowhead because the orders service publishes the event and moves on. It doesn't wait for whoever consumes the queue.
  • The else branch 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:

API retry flow

sequenceDiagram
participant M as Mobile App
participant G as API Gateway
participant O as Orders Service
M->>+G: POST /orders
loop At most 3 attempts
G->>+O: createOrder
alt Saved
O-->>G: 201 Created
else Timed out
G->>G: Back off
end
deactivate O
end
G-->>-M: Result

Rename a participant or add a Note over G,O line and watch the diagram change.

64 words380 characters21 lines
Markdown

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:

  1. The loop repeats the reservation once per line item. One frame replaces what would otherwise be a long column of identical arrows.
  2. The opt block applies a discount only when the buyer typed a code. It has one operand and no else, which is exactly what separates opt from alt.
  3. The payment call is synchronous, so the provider gets a short activation bar.
  4. 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.
  5. 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:

  1. Pick one scenario. Name it in a sentence, such as buyer checks out with a declined card.
  2. List the participants in the order they're first called, left to right. Put the actor that starts the flow on the far left.
  3. Write the happy path as messages from top to bottom, then add a reply for each synchronous call.
  4. Mark who's busy with activation bars, mainly on the services that do real work.
  5. Wrap branches and repeats in alt, opt, loop or break, each with a guard.
  6. 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.