Mermaid Sequence Diagrams — Participants, Messages, and Loops

What is a Sequence Diagram?

A sequence diagram shows how different actors or systems interact over time. Messages flow from left to right between vertical lifelines, making it ideal for illustrating API calls, authentication flows, and microservice communication.

Defining Participants

Participants appear as boxes at the top of the diagram. You can declare them explicitly to control ordering:

sequenceDiagram
    participant Browser
    participant API
    participant DB as Database

Use the as keyword to give a participant a display alias. You can also use actor instead of participant to render a stick figure icon.

Message Types

Mermaid supports several arrow styles to represent different kinds of communication:

Syntax	Meaning
->>	Synchronous request (solid arrow)
-->>	Asynchronous / return (dashed arrow)
-)	Asynchronous fire-and-forget (open arrow)
--)	Async fire-and-forget return (dashed open)

Activation and Deactivation

Show when a participant is actively processing with activate / deactivate or the shorthand + / -:

sequenceDiagram
    Browser->>+API: POST /login
    API->>+DB: SELECT user
    DB-->>-API: user record
    API-->>-Browser: 200 OK + JWT

Loops, Alternatives, and Options

Control flow blocks let you model conditional logic and repetition:

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Request resource
    alt Cache hit
        Server-->>Client: 304 Not Modified
    else Cache miss
        Server->>Server: Generate response
        Server-->>Client: 200 OK + payload
    end

    loop Every 30 seconds
        Client->>Server: Heartbeat ping
        Server-->>Client: pong
    end

Notes

Add contextual notes alongside messages:

sequenceDiagram
    Alice->>Bob: Hello
    Note right of Bob: Bob thinks about it
    Bob-->>Alice: Hi back!
    Note over Alice, Bob: They are now friends

Notes can be placed right of, left of, or over one or more participants.