Guide

How to Create Sequence Diagrams with Mermaid

Sequence diagrams show how objects or actors exchange messages over time — perfect for documenting API flows, user interactions, and system architecture.

1. Basic Syntax

Every sequence diagram starts with the sequenceDiagram keyword, followed by participants and messages:

Example Code

sequenceDiagram
    Participant User
    Participant Server
    Participant Database

    User->>Server: GET /api/users
    Server->>Database: SELECT * FROM users
    Database-->>Server: results
    Server-->>User: 200 OK

2. Message Arrow Types

Arrow style determines the type of communication:

->>Synchronous message (solid)User->>Server: request

-->>Return message (dotted)Server-->>User: response

-)Asynchronous message (open arrow)Client-)Server: async event

--)Asynchronous return (dotted open)Server--)Client: ack

->Solid line without arrowheadA->B: signal

-->Dotted line without arrowheadA-->B: dotted signal

3. Activations

Activate and deactivate show when a participant is actively executing a process:

Example Code

sequenceDiagram
    User->>Server: POST /api/orders
    activate Server
        Server->>Database: INSERT order
        activate Database
        Database-->>Server: order_id: 42
        deactivate Database
        Server->>Queue: Publish event
        activate Queue
        Queue-->>Server: acknowledged
        deactivate Queue
    Server-->>User: 201 Created {order_id: 42}
    deactivate Server

4. Notes

Add contextual notes to any part of the diagram:

Example Code

sequenceDiagram
    User->>Auth: POST /login
    Note right of Auth: Credentials verified against DB
    Auth->>Session: Create session token
    Note left of Session: Token stored in Redis
    Session-->>Auth: token
    Auth-->>User: 200 OK {token}

5. Loops, Alt, and Opt

Control flow structures for complex scenarios:

Loop — loop ... end

loop Every 30 seconds
    Monitor->>API: GET /health
    API-->>Monitor: 200 OK
end

Repeats a sequence while a condition is true

Alt (Alternative) — alt ... else ... end

alt User is logged in
    User->>Dashboard: Show dashboard
else User is not logged in
    User->>Login: Redirect to login
end

Shows mutually exclusive paths

Opt (Optional) — opt ... end

opt Rate limit exceeded
    API-->>Client: 429 Too Many Requests
end

Executes only under certain conditions

Par (Parallel) — par ... and ... end

par Send email and SMS
    Server->>Email: Send email
and
    Server->>SMS: Send SMS
end

Multiple messages sent simultaneously

6. Real-World API Example

A complete user registration and email verification flow:

Example Code

Try it live →

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Auth
    participant Email

    User->>Frontend: Submit registration form
    Frontend->>API: POST /register {email, password}
    activate API
        API->>Auth: Create user account
        activate Auth
        Auth-->>API: user_id
        deactivate Auth
        API->>Email: Send verification email
        activate Email
        Email-->>API: Email sent
        deactivate Email
        API-->>Frontend: 201 Created {user_id}
    deactivate API
    User->>Email: Open verification link
    Email->>API: GET /verify?token=xyz
    API->>Auth: Validate token
    Auth-->>API: Email verified
    API-->>User: Email verified successfully

Pro Tips

→Use activate/deactivate to keep diagrams clean — only show active participants
→Keep messages short and action-oriented (verb + noun)
→Use alt/else for error handling paths — very common in API docs
→Use loop for polling, retry, or heartbeat patterns
→Left-to-right ordering matters — put the initiator on the left
→Use notes to explain non-obvious decisions or side effects

Start creating sequence diagrams now

No signup required. Just open mermaid.bkkdev.io and start typing.

Open Mermaid Viewer →