
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.
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:

| Element | How it is drawn | Meaning |
|---|---|---|
| Lifeline | A box with the participant's name and a dashed vertical line | A person, object, service or system taking part |
| Actor | Stick figure on top of a lifeline | A human or external role |
| Activation bar | Thin rectangle on a lifeline | The participant is busy handling a call |
| Synchronous message | Solid line, filled arrowhead | The caller waits for a response |
| Asynchronous message | Solid line, open arrowhead | The caller continues without waiting |
| Reply message | Dashed line, open arrowhead | The result of an earlier call |
| Create message | Dashed arrow to a new lifeline's head | A participant is created mid-scenario |
| Destruction | An X at the end of a lifeline | The participant stops existing |
| Combined fragment | A frame with an operator such as alt or loop | Conditional, 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 add logic without turning the diagram into a flowchart. A guard in square brackets, such as [password valid], decides whether an operand runs.

| Operator | Use it for | Code equivalent |
|---|---|---|
alt | Choose one of several branches | if / else |
opt | One optional branch | if |
loop | Repeat while a guard holds | for / while |
par | Operands that run in parallel | concurrent calls |
break | Run, then leave the enclosing fragment | early return |
critical | A section that must not be interleaved | lock / transaction |
ref | Reuse 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.
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.

findUser(email), POST /login.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.
| Diagram | Shows | Pick it when |
|---|---|---|
| Sequence diagram | Messages between participants in time order | Order of calls matters |
| Communication diagram | The same messages, numbered, on a network of objects | Links between objects matter more than timing |
| Activity diagram | Steps, decisions and parallel flows of a process | You 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.
Checked on October 28, 2026.
| Tool | Type | Free use | Good for |
|---|---|---|---|
| sequencediagram.org | Text and click, in the browser | Free | Quick diagrams with full fragment support |
| Mermaid | Text, open source | Free | Diagrams in Markdown, GitHub and docs |
| PlantUML | Text, open source (GPL) | Free | Detailed UML in code repositories |
| draw.io | Visual editor | Free, no account | Drag-and-drop UML shapes |
| Visual Paradigm Community Edition | Desktop UML modeler | Free for non-commercial use | Students and full UML modeling |
| AFFiNE | Docs and whiteboard | Free local use; free cloud plan | Keeping 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.
ref.else branch.
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.
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.
A synchronous message (filled arrowhead) means the caller waits for a response. An asynchronous message (open arrowhead) means the caller continues without waiting.
A dashed line with an open arrowhead is a reply. A dashed arrow pointing to a participant's head is a create message.
Yes. Mermaid and PlantUML both turn short text into sequence diagrams, and sequencediagram.org uses a similar text syntax in the browser.
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.