Mermaid Sequence Diagram Generator

Mermaid Sequence Diagram Syntax

Sequence diagrams show how components interact over time. Each vertical line is a participant (service, user, system), and horizontal arrows are messages passed between them. They are the standard way to document API flows, authentication handshakes, and distributed system interactions.

Participants

Declare participants to control their order from left to right:

sequenceDiagram
    participant Browser
    participant API
    participant Database

Without explicit participant declarations, Mermaid creates them in the order they first appear. Use actor instead of participant to render a stick figure icon (useful for human users).

Message Types

The convention: solid lines for requests, dashed lines for responses. ->> (filled arrowhead) is the most common.

Activation Bars

Show when a participant is actively processing:

sequenceDiagram
    Client->>+API: Request
    API->>+DB: Query
    DB-->>-API: Result
    API-->>-Client: Response

The + after ->> activates the target. The - deactivates it. Activation bars stack if a participant is activated multiple times. Alternatively, use explicit activate API and deactivate API statements.

Control Flow

Conditionals

alt Success
    API-->>Client: 200 OK
else Not Found
    API-->>Client: 404
else Server Error
    API-->>Client: 500
end

Loops

loop Every 30 seconds
    Client->>API: Heartbeat
    API-->>Client: ACK
end

Optional

opt Has cache
    API->>Cache: Get cached result
    Cache-->>API: Cached data
end

Parallel

par Upload avatar
    Client->>Storage: PUT /avatar
and Update profile
    Client->>API: PATCH /profile
end

Notes

Note left of API: Validates JWT
Note right of DB: Read replica
Note over Client,API: HTTPS only

Notes can span multiple participants with Note over A,B: text. They render as yellow sticky notes attached to the timeline.

Numbering

Add autonumber after sequenceDiagram to automatically number every message. Useful for referencing specific steps in documentation (“see step 4 in the diagram”).

Practical Patterns

REST API authentication

The initial state of this example shows a complete login flow followed by an authenticated request. This pattern appears in nearly every web application and makes a good starting point for documenting your own API.

Webhook delivery

sequenceDiagram
    participant App
    participant Webhook
    participant Consumer

    App->>Webhook: POST /webhooks/events
    Webhook->>Consumer: POST callback_url
    alt 2xx
        Consumer-->>Webhook: 200 OK
        Webhook-->>App: delivered
    else Timeout
        Webhook->>Webhook: Schedule retry
        Webhook->>Consumer: POST callback_url (retry 1)
    end

Database transaction

sequenceDiagram
    participant Service
    participant DB

    Service->>DB: BEGIN
    Service->>DB: INSERT INTO orders
    Service->>DB: UPDATE inventory
    alt All succeeded
        Service->>DB: COMMIT
    else Error
        Service->>DB: ROLLBACK
    end

For data model documentation, the Mermaid ER Diagram shows table relationships. For process flows without time ordering, use the Mermaid Flowchart.