How to Draw Sequence Diagrams in Mermaid

2026-03-04 · MermZen Tutorial

Sequence diagrams show interactions between participants over time. They answer the question: Who sends what to whom at which moment? Perfect for API flows, user-system interaction, and microservice communication.

Why Use Sequence Diagrams?

Sequence diagrams are the best choice for showing interaction flows:

• Show message interactions between multiple participants — Clearly present "who does what to whom"
• Perfect for API call chains — Frontend → Backend → Database → Cache, all at a glance
• Clearly express "who sends what to whom at which moment" — Timeline flows top to bottom, intuitive order

sequenceDiagram
    actor User
    participant Frontend
    participant API as API Server
    participant Database
    
    User->>Frontend: Click login
    Frontend->>API: POST /api/login
    API->>Database: SELECT * FROM users
    Database-->>API: User data
    API-->>Frontend: 200 OK + Token
    Frontend-->>User: Redirect to dashboard

Declaring Participants

sequenceDiagram
    participant User
    participant Server
    participant Database

• sequenceDiagram declares the diagram type
• participant name controls the order of participants (left → right)
• actor name renders as a stick figure (for human users)
• participant A as Alias creates aliases for readability

Message Types

sequenceDiagram
    A->>B: Solid open arrow (synchronous)
    B-->>A: Dashed open arrow (response)
    A-)B: Solid async arrow
    A--)B: Dashed async arrow
    A-xB: Solid with cross (failure)

Arrow Type Selection Guide

Choose the right arrow type to make your diagram semantically clearer:

sequenceDiagram
    participant Client
    participant Server
    
    Client->>Server: HTTP request (sync)
    Server-->>Client: HTTP response (return)
    
    Client-)Server: WebSocket message (async)
    Server--)Client: Push notification (async response)
    
    Client-xServer: Request timeout (failure)

Best Practices

Participant Naming Conventions

• Use actor for real users (renders as stick figure)
• Use participant for system components (services, databases, caches, etc.)
• Use as keyword for short aliases to keep code concise

Add Key Notes

Use note to add explanations for key steps, helping readers understand complex logic:

sequenceDiagram
    participant A
    participant B
    Note right of A: Note for A
    Note over A,B: Note spanning multiple participants
    A->>B: Message

Control Participant Count

Recommended: no more than 5 participants. Too many participants make diagrams hard to read. For complex systems:

• Split into multiple sequence diagrams
• Use box to group related participants
• Omit minor intermediate steps

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Cache
    participant Database
    
    Note over User,Database: Recommended: max 5 participants
    
    User->>Frontend: Send request
    Frontend->>API: API call
    API->>Cache: Query cache
    Cache-->>API: Cache hit
    API-->>Frontend: Return result
    Frontend-->>User: Display data

Comparison with Other Diagrams

Selection Guide:

• Need to show who does what to whom → Sequence Diagram
• Need to show conditional branches and loops → Flowchart
• Need to show complete business process → Activity Diagram

Control Structures

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

    alt Credentials valid
        Server-->>Client: 200 OK
    else Invalid
        Server-->>Client: 401 Unauthorized
    end

Full Example: HTTP Login Flow

sequenceDiagram
    actor User
    participant Browser
    participant APIServer
    participant Redis
    participant MySQL

    User->>Browser: Submit login
    Browser->>APIServer: POST /api/login {username, password}

    APIServer->>Redis: GET login_fail:{username}
    Redis-->>APIServer: Fail count (0)

    APIServer->>MySQL: SELECT * FROM users WHERE username=?
    MySQL-->>APIServer: User record

    alt Password valid
        APIServer->>APIServer: Generate JWT Token (HS256)
        APIServer->>Redis: SET session:{token} 7d
        APIServer-->>Browser: 200 OK {token, user}
        Browser->>Browser: Store in localStorage
        Browser-->>User: Redirect to dashboard
    else Wrong password
        APIServer->>Redis: INCR login_fail:{username}
        APIServer-->>Browser: 401 {error: "Invalid password"}
        Browser-->>User: Show error message
    end

To try the above code in MermZen, click Open Editor and paste the code there.