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.

Updated November 19, 2026 · 2 min read

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 cookie

Participants 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 receipt

Arrow 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 OK

Notes

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 code

Loops, alternatives and optional steps

Blocks group messages and end with end:

  • loop for repetition
  • alt with one or more else for branches
  • opt for a step that may not happen
  • par with and for parallel messages
  • critical and break for must-succeed steps and early exits
  • rect 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
  end

Number 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 dashboard

Tips

  • Keep each diagram to one scenario. Put the error path in its own diagram, or in an alt block, 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