How to write a mermaid sequence diagram
A sequence diagram shows who talks to whom, in what order. In mermaid it takes about as long to write as it takes to describe out loud, which is why it is the diagram type that survives longest in a codebase. Everything below is copy-paste ready for the editor.
The minimum
Declare the diagram type, then write one line per message. Participants are created on first mention, in the order they appear.
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order id
API-->>User: 201 CreatedDeclare participants explicitly with participant User when you want a specific left-to-right order rather than the order of first mention.
Arrow types
| Syntax | Meaning |
|---|---|
A->>B: text | Request — solid line, filled arrowhead |
A-->>B: text | Response — dashed line, filled arrowhead |
A->B: text | Solid line, open arrowhead |
A-)B: text | Async message — open arrowhead, no reply expected |
A-xB: text | Message that fails or is dropped |
The convention worth keeping: solid for the call, dashed for the return. A reader can then tell a request from a response without reading a single label.
Participants and aliases
sequenceDiagram
participant U as Browser
participant A as API gateway
participant S as Order service
U->>A: GET /orders
A->>S: list(userId)
S-->>A: orders
A-->>U: 200 OKUse actor U as Browser instead of participant to draw a stick figure — worth it for the human at the left edge of an authentication flow.
Activation bars
Activation bars show how long a participant is busy. Either mark them explicitly with activate/deactivate, or append + and - to the arrows, which is shorter and harder to get out of balance.
sequenceDiagram
User->>+API: POST /pay
API->>+Bank: charge
Bank-->>-API: authorised
API-->>-User: receiptLoops, conditionals and parallel work
sequenceDiagram
User->>API: POST /import
loop every row
API->>DB: upsert row
end
alt all rows valid
API-->>User: 200 OK
else some failed
API-->>User: 422 with errors
end
par notify
API->>Email: send summary
and audit
API->>Log: write entry
endloop <label>…end— repetition.alt <label>…else <label>…end— mutually exclusive branches.opt <label>…end— a branch that may simply not happen.par <label>…and <label>…end— things happening at the same time.critical/break— a section that must not be interrupted, and an early exit.
Notes
sequenceDiagram
User->>API: POST /login
Note right of API: Rate limited<br>5 per minute
API-->>User: token
Note over User,API: Token is valid for 30 daysNote over A,B spans two participants and is the right place for a constraint that belongs to the interaction rather than to either side of it.
A full example
sequenceDiagram
actor U as User
participant A as App
participant P as Provider
U->>+A: Click "Sign in"
A-->>-U: Redirect to provider
U->>+P: Authorise
P-->>-U: Redirect back with code
U->>+A: GET /callback?code=…
A->>+P: Exchange code for token
P-->>-A: access token
Note right of A: Session cookie set here
A-->>-U: Signed inEdit this diagram
Paste it into the code tab and change a line — the preview redraws as you type.
Frequently asked
How do I number the messages?
Put autonumber on the line right after sequenceDiagram. Every message then gets a sequential number, which makes a diagram much easier to talk about in review comments.
Can a participant send a message to itself?
Yes — write the same name on both sides: API->>API: retry. Mermaid draws the loop back into the same lifeline.
How do I show that a participant is destroyed?
Use destroy <name> before the message that ends it, or create participant <name> to have it appear mid-diagram rather than at the top.
Can I edit a sequence diagram on the visual canvas?
The visual canvas edits flowcharts. Sequence diagrams are written on the code tab, where they render live in the preview — which is usually faster anyway, since a sequence diagram is essentially a list of lines.