All posts
Allen
Author, Content Operations Manager·Originally published Feb 20, 2026 · Updated Oct 28, 2026
UML sequence diagram with User, Web app and Auth API lifelines, activation bars, synchronous calls and dashed reply messages

UML Sequence Diagram: Notation, Fragments & Examples

A UML sequence diagram shows how participants in a system exchange messages over time. Each participant gets a vertical lifeline, messages are horizontal arrows, and time runs from top to bottom. Use one when you need to explain the order of calls in a single scenario, such as a login, a checkout, or an API request. This guide covers the notation, combined fragments such as alt and loop, a complete login example, and the same diagram in Mermaid and PlantUML.

Notation in this guide follows the OMG UML 2.5.1 specification (December 2017), the current formal version. The login example is fictional.

What is a sequence diagram in UML?

A sequence diagram is one of the UML interaction diagrams. It answers one question: in this scenario, who calls whom, in what order, and what comes back? A UML class diagram shows a system's static structure; a sequence diagram shows one path through its behavior.

Teams use sequence diagrams to:

  • design or review an API flow before writing code
  • explain a bug that depends on timing or call order
  • document how services, queues and databases work together
  • agree on error handling, such as what happens when a payment fails

UML sequence diagram notation

UML sequence diagram notation: lifeline, activation bar, synchronous, asynchronous, reply and create messages, destruction X and a combined fragment frame

ElementHow it is drawnMeaning
LifelineA box with the participant's name and a dashed vertical lineA person, object, service or system taking part
ActorStick figure on top of a lifelineA human or external role
Activation barThin rectangle on a lifelineThe participant is busy handling a call
Synchronous messageSolid line, filled arrowheadThe caller waits for a response
Asynchronous messageSolid line, open arrowheadThe caller continues without waiting
Reply messageDashed line, open arrowheadThe result of an earlier call
Create messageDashed arrow to a new lifeline's headA participant is created mid-scenario
DestructionAn X at the end of a lifelineThe participant stops existing
Combined fragmentA frame with an operator such as alt or loopConditional, repeated or parallel parts

Name a lifeline name:Type (for example cart:ShoppingCart) when the type matters, or just the role (Web app) for an architecture-level diagram.

Combined fragments: alt, opt, loop and more

Combined fragments add logic without turning the diagram into a flowchart. A guard in square brackets, such as [password valid], decides whether an operand runs.

Combined fragments cheat sheet: alt, opt, loop, par, break, critical and ref frames with example guards

OperatorUse it forCode equivalent
altChoose one of several branchesif / else
optOne optional branchif
loopRepeat while a guard holdsfor / while
parOperands that run in parallelconcurrent calls
breakRun, then leave the enclosing fragmentearly return
criticalA section that must not be interleavedlock / transaction
refReuse another sequence diagram (an interaction use)function call

UML 2.5.1 defines more operators (neg, assert, strict, seq, ignore, consider), but the seven above cover most diagrams.

Example: a login sequence diagram

The diagram below shows a fictional login. The user submits credentials, the web app calls an auth API, the API looks up the user, and an alt fragment covers the success and failure paths. The audit event is asynchronous because the API does not wait for the log service.

UML sequence diagram of a fictional login: User, Web app, Auth API, User DB and Log service lifelines with an alt fragment for valid and invalid passwords

How to draw a sequence diagram, step by step

  1. Pick one scenario. "User logs in with a valid password" is a scenario; "authentication" is not.
  2. List the participants from left to right in the order they are first called.
  3. Add messages top to bottom. Use a verb or an API call as the label: findUser(email), POST /login.
  4. Choose the arrow type. Solid filled for calls that wait, open for fire-and-forget, dashed for replies.
  5. Add fragments for branches and loops, each with a guard.
  6. Add activation bars if timing matters; skip them for high-level diagrams.
  7. Check it against the code or API spec, and keep one diagram per scenario rather than one diagram for everything.

The same diagram as code: Mermaid and PlantUML

Writing diagrams as text keeps them in version control next to the code. Mermaid renders in GitHub Markdown and many documentation tools.

sequenceDiagram
    actor User
    participant Web as Web app
    participant Auth as Auth API
    participant DB as User DB
    participant Log as Log service
    User->>Web: submit(email, password)
    Web->>Auth: POST /login
    Auth->>DB: findUser(email)
    DB-->>Auth: user record
    alt password valid
        Auth-)Log: audit event
        Auth-->>Web: 200 OK + session token
    else invalid
        Auth-->>Web: 401 Unauthorized
    end
    Web-->>User: dashboard or error message

PlantUML is free, GPL-licensed, and popular in Java and enterprise documentation:

@startuml
actor User
participant "Web app" as Web
participant "Auth API" as Auth
database "User DB" as DB
participant "Log service" as Log
User -> Web: submit(email, password)
Web -> Auth: POST /login
Auth -> DB: findUser(email)
DB --> Auth: user record
alt password valid
  Auth ->> Log: audit event
  Auth --> Web: 200 OK + session token
else invalid
  Auth --> Web: 401 Unauthorized
end
Web --> User: dashboard or error message
@enduml

In Mermaid, ->> is a call, -->> is a reply and -) is an asynchronous message. In PlantUML, -> is a call, --> is a reply and ->> draws an open (asynchronous) arrowhead.

Sequence diagram vs. communication and activity diagrams

DiagramShowsPick it when
Sequence diagramMessages between participants in time orderOrder of calls matters
Communication diagramThe same messages, numbered, on a network of objectsLinks between objects matter more than timing
Activity diagramSteps, decisions and parallel flows of a processYou are modeling a workflow, not object interaction

For how data moves and where it is stored, rather than call order, use a data flow diagram. For the structure of the data itself, use an ER diagram tool.

Free tools for UML sequence diagrams

Checked on October 28, 2026.

ToolTypeFree useGood for
sequencediagram.orgText and click, in the browserFreeQuick diagrams with full fragment support
MermaidText, open sourceFreeDiagrams in Markdown, GitHub and docs
PlantUMLText, open source (GPL)FreeDetailed UML in code repositories
draw.ioVisual editorFree, no accountDrag-and-drop UML shapes
Visual Paradigm Community EditionDesktop UML modelerFree for non-commercial useStudents and full UML modeling
AFFiNEDocs and whiteboardFree local use; free cloud planKeeping the diagram next to the design doc

AFFiNE has no UML-specific shapes. Draw lifelines and messages with shapes and connectors, or start from the sequence diagram template, and write the API notes and decisions in the same document.

To place this scenario in the bigger picture, see the system context diagram and software architecture diagram guides.

Common mistakes

  • One giant diagram. Split by scenario and connect them with ref.
  • Mixing levels. Do not combine HTTP endpoints and internal method calls in one diagram unless the reader needs both.
  • Missing replies or error paths. Most bugs live in the else branch.
  • Unlabelled arrows. Every message needs a name.
  • Using a sequence diagram for a workflow. If there is no interaction between participants, an activity diagram or flowchart is clearer.

Frequently asked questions

What is a sequence diagram used for?

It shows how participants exchange messages over time in one scenario. Developers use it to design API flows, review service interactions, and explain bugs that depend on call order.

How do you show if/else in a sequence diagram?

Use an alt combined fragment. Each operand has a guard such as [paid] or [else], separated by a dashed line. For a single optional branch, use opt.

What is the difference between synchronous and asynchronous messages?

A synchronous message (filled arrowhead) means the caller waits for a response. An asynchronous message (open arrowhead) means the caller continues without waiting.

What do the dashed arrows mean?

A dashed line with an open arrowhead is a reply. A dashed arrow pointing to a participant's head is a create message.

Can I write a sequence diagram as code?

Yes. Mermaid and PlantUML both turn short text into sequence diagrams, and sequencediagram.org uses a similar text syntax in the browser.

Start with the free template

Open the free sequence diagram template in AFFiNE or download AFFiNE to keep your diagrams and design notes together.

Update note (October 28, 2026): This article was first published in February 2026 and rewritten in October 2026 to focus on notation. We added a full notation table, combined fragments, an original login example with Mermaid and PlantUML code, and a comparison with communication and activity diagrams. We removed an off-topic section on UML collection types and unrelated links, and replaced the shared cover with original images. AI tools assisted with drafting, and the content was reviewed and edited by the AFFiNE team.