Mermaid sequence diagrams: a step-by-step tutorial
Learn Mermaid sequence diagrams from the first message to a full sign-in flow: participants and actors, arrow types, activations, notes, loops, alternatives and numbering.
A sequence diagram shows who talks to whom, in what order. It is the clearest way to explain an API call, a sign-in flow or a payment, and in Mermaid it reads almost like the conversation itself. This tutorial builds one up a feature at a time.
Your first sequence diagram
Start with sequenceDiagram, then write one message per line: sender, arrow, receiver, colon, text.
sequenceDiagram
Browser->>Server: POST /login
Server->>Database: Find user by email
Database-->>Server: User record
Server-->>Browser: 200 OK and a session cookieParticipants appear in the order they are first mentioned. Solid arrows are calls; dotted arrows are replies.
Participants, actors and aliases
Declare participants up front to control their order and give them short ids with readable names. Use actor for a person.
sequenceDiagram
actor U as Customer
participant W as Web app
participant P as Payments API
U->>W: Click "Pay"
W->>P: Create payment
P-->>W: Payment confirmed
W-->>U: Show receiptArrow types
| Syntax | Meaning |
|---|---|
A->>B |
Solid line with an arrowhead (a call) |
A-->>B |
Dotted line with an arrowhead (a reply) |
A->B |
Solid line, no arrowhead |
A-->B |
Dotted line, no arrowhead |
A-xB |
Solid line ending in a cross (failed or lost) |
A--xB |
Dotted line ending in a cross |
A-)B |
Solid line with an open arrow (asynchronous) |
A--)B |
Dotted line with an open arrow |
Activations
An activation bar shows when a participant is busy. Add + after the arrow to start one and - to end it:
sequenceDiagram
Client->>+API: GET /orders
API->>+Database: SELECT orders
Database-->>-API: 12 rows
API-->>-Client: 200 OKNotes
Notes explain what happens inside a step. Place them left of, right of or over one or two participants.
sequenceDiagram
participant App
participant Auth
Note over App: Generate a PKCE verifier and challenge
App->>Auth: /authorize with the challenge
Note right of Auth: Checks the client and redirect URI
Auth-->>App: Authorization codeLoops, alternatives and optional steps
Blocks group messages and end with end:
loopfor repetitionaltwith one or moreelsefor branchesoptfor a step that may not happenparwithandfor parallel messagescriticalandbreakfor must-succeed steps and early exitsrect rgb(...)to highlight a region
sequenceDiagram
participant W as Worker
participant Q as Queue
participant S as Service
loop Every 5 seconds
W->>Q: Poll for messages
end
alt Message received
W->>S: Process it
S-->>W: Done
else Queue empty
W->>W: Sleep
end
opt Error rate above 1%
W->>S: Send an alert
endNumber the steps
Put autonumber on the second line and every message gets a number, which makes a diagram easy to discuss ("step 4 fails").
A complete example: sign-in with OAuth and PKCE
sequenceDiagram
autonumber
actor U as User
participant A as Single-page app
participant I as Identity provider
participant R as Resource API
U->>A: Click "Sign in"
Note over A: Create a code verifier and challenge
A->>I: GET /authorize with the challenge
I-->>U: Ask for credentials and MFA
U->>I: Sign in
I-->>A: Redirect with an authorization code
A->>+I: POST /token with the code and verifier
I-->>-A: ID token and access token
A->>+R: GET /workspace with the access token
R-->>-A: 200 OK
A-->>U: Show the dashboardTips
- Keep each diagram to one scenario. Put the error path in its own diagram, or in an
altblock, rather than both in one long chain. - Name messages after what they do ("Create payment"), not the function ("createPmt").
- Use replies consistently: dotted for responses makes the call structure obvious.
In Flowgraph Studio, sequence diagrams pick up your theme, and Manual mode lets you add, rename and reorder participants and messages on the canvas while the Mermaid code stays in step. When the flow changes, Compare versions lines up two versions and marks the participants and messages that were added, removed, reworded or moved to other participants. Ready-made sequences, such as an OAuth sign-in, a web request with a cache, and webhook retries, are on the Templates page.
For the other diagram you'll draw most, see the Mermaid flowchart cheat sheet.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.