Mermaid Sequence Diagrams

Sequence diagrams describe interactions between components, services, or users in chronological order. They are invaluable for documenting APIs, authentication protocols, microservice interactions, and user flows.

Basic Syntax

sequenceDiagram
    participant Browser
    participant API
    participant DB

    Browser->>API: POST /auth/login
    API->>DB: SELECT user WHERE email=?
    DB-->>API: user record
    API-->>Browser: 200 OK { token }

Participants

By default, participants appear in order of first mention. For explicit ordering and aliases:

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant D as Database

    U->>F: Opens page
    F->>B: GET /api/tasks
    B->>D: SELECT * FROM tasks
    D-->>B: tasks[]
    B-->>F: 200 { tasks }
    F-->>U: Renders list

Actors

Use actor instead of participant to display people as stick figures:

sequenceDiagram
    actor User as 👤 User
    participant App
    participant Server

    User->>App: Click "Create Task"
    App->>Server: POST /api/tasks
    Server-->>App: 201 Created
    App-->>User: Task added

Message Types

Activations

sequenceDiagram
    Client->>+Server: Request
    Server->>+DB: Query
    DB-->>-Server: Data
    Server-->>-Client: Response

+ activates the participant, - deactivates it.

Notes

sequenceDiagram
    Alice->>Bob: Hello!
    Note right of Bob: Bob thinks...
    Bob-->>Alice: Hello!
    Note over Alice,Bob: They are communicating

Conditional Blocks

alt — branches

sequenceDiagram
    Client->>Server: Request with token
    alt Token valid
        Server-->>Client: 200 OK
    else Token expired
        Server-->>Client: 401 Unauthorized
    else Token missing
        Server-->>Client: 403 Forbidden
    end

opt — optional block

sequenceDiagram
    User->>App: Save settings
    App->>Server: PATCH /settings
    opt Notifications enabled
        Server->>Email: Send confirmation
    end
    Server-->>App: 200 OK

par — parallel operations

sequenceDiagram
    Server->>Server: Request received

    par Parallel processing
        Server->>Cache: Invalidate cache
    and
        Server->>DB: Update data
    and
        Server->>Analytics: Record event
    end

    Server-->>Client: Response

Loops

sequenceDiagram
    Client->>Server: Start polling

    loop Every 5 seconds
        Client->>Server: GET /status
        Server-->>Client: { status: "processing" }
    end

    Server-->>Client: { status: "done" }

Example: OAuth 2.0 Authorization

sequenceDiagram
    actor User as 👤 User
    participant App
    participant Auth as OAuth Provider
    participant API as Resource API

    User->>App: Sign in with GitHub
    App->>Auth: Redirect /oauth/authorize
    Auth->>User: Authorization page
    User->>Auth: Grants access
    Auth-->>App: code=abc123
    App->>Auth: POST /oauth/token {code}
    Auth-->>App: access_token, refresh_token
    App->>API: GET /user {Bearer token}
    API-->>App: user data
    App-->>User: Signed in as @username