← All Articles

Mermaid Sequence Diagram Tutorial with Examples

Learn how to create sequence diagrams with Mermaid.js. Covers participants, messages, loops, alt blocks, notes, and activation with real-world examples.

What Are Sequence Diagrams?

Sequence diagrams show how different components or actors interact over time. They're perfect for documenting API calls, microservice communication, authentication flows, and any process where the order of messages matters.

Mermaid makes sequence diagrams easy to write and maintain — no drawing tools needed.

Basic Syntax

sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: Great!
Try in Editor →

The key elements:

  • Participants are automatically created when first mentioned
  • Solid arrow (->>) = synchronous message
  • Dashed arrow (-->>) = response / async message
  • Messages are labeled after the colon

Arrow Types

Mermaid supports several arrow types for different message semantics:

sequenceDiagram
    A->>B: Solid line with arrowhead (sync call)
    B-->>A: Dotted line with arrowhead (response)
    A-)B: Solid line with open arrow (async)
    B--)A: Dotted line with open arrow (async response)
    A-xB: Solid line with cross (lost message)
    B--xA: Dotted line with cross
Try in Editor →

Defining Participants

You can explicitly declare participants to control order and add aliases:

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as API Server
    participant D as Database

    U->>F: Click "Login"
    F->>A: POST /auth/login
    A->>D: SELECT user WHERE email=?
    D-->>A: User record
    A-->>F: JWT token
    F-->>U: Redirect to dashboard
Try in Editor →

Use actor instead of participant to show a stick figure:

sequenceDiagram
    actor User
    participant API
    User->>API: Request
    API-->>User: Response
Try in Editor →

Activation Bars

Activation bars show when a participant is actively processing:

sequenceDiagram
    Client->>+Server: HTTP Request
    Server->>+Database: Query
    Database-->>-Server: Results
    Server-->>-Client: HTTP Response
Try in Editor →

The + activates (starts the bar) and - deactivates (ends it). You can also use explicit syntax:

sequenceDiagram
    Client->>Server: Request
    activate Server
    Server->>Database: Query
    activate Database
    Database-->>Server: Results
    deactivate Database
    Server-->>Client: Response
    deactivate Server
Try in Editor →

Real-World Example: OAuth 2.0 Flow

sequenceDiagram
    actor User
    participant App as Client App
    participant Auth as Auth Server
    participant API as Resource Server

    User->>App: Click "Login with Google"
    App->>Auth: Redirect to /authorize
    Auth->>User: Show consent screen
    User->>Auth: Grant permission
    Auth-->>App: Authorization code
    App->>+Auth: Exchange code for token
    Auth-->>-App: Access token + Refresh token
    App->>+API: GET /user (Bearer token)
    API-->>-App: User profile data
    App-->>User: Show profile
Try in Editor →

Loops

Show repeated interactions:

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Connect
    loop Every 30 seconds
        Client->>Server: Heartbeat ping
        Server-->>Client: Pong
    end
    Client->>Server: Disconnect
Try in Editor →

Alt / Else Blocks (Conditionals)

Show branching logic:

sequenceDiagram
    participant User
    participant API
    participant DB

    User->>API: POST /login
    API->>DB: Check credentials
    alt Valid credentials
        DB-->>API: User found
        API-->>User: 200 OK + Token
    else Invalid credentials
        DB-->>API: Not found
        API-->>User: 401 Unauthorized
    end
Try in Editor →

Optional Blocks

The opt block shows something that may or may not happen:

sequenceDiagram
    participant User
    participant Cart
    participant Payment

    User->>Cart: Add items
    User->>Cart: Checkout
    opt Has coupon
        User->>Cart: Apply coupon code
        Cart-->>User: Discount applied
    end
    Cart->>Payment: Process payment
    Payment-->>Cart: Confirmation
    Cart-->>User: Order complete
Try in Editor →

Parallel (Par) Blocks

Show things happening simultaneously:

sequenceDiagram
    participant App
    participant UserSvc as User Service
    participant OrderSvc as Order Service
    participant NotifSvc as Notification Service

    App->>App: User places order
    par Parallel requests
        App->>UserSvc: Get user details
        App->>OrderSvc: Create order
        App->>NotifSvc: Send confirmation
    end
    UserSvc-->>App: User data
    OrderSvc-->>App: Order ID
    NotifSvc-->>App: Sent OK
Try in Editor →

Notes

Add notes for extra context:

sequenceDiagram
    participant C as Client
    participant S as Server

    Note over C,S: TLS Handshake
    C->>S: ClientHello
    S-->>C: ServerHello + Certificate
    C->>S: Key Exchange
    Note over C,S: Encrypted connection established

    C->>S: GET /api/data
    Note right of S: Validate token, query DB
    S-->>C: 200 OK + JSON
Try in Editor →

Note positions: Note left of, Note right of, Note over A,B (spans multiple participants).

Critical Regions

Highlight critical sections:

sequenceDiagram
    participant App
    participant DB

    App->>DB: BEGIN TRANSACTION
    critical Database Transaction
        App->>DB: UPDATE accounts SET balance = balance - 100 WHERE id = 1
        App->>DB: UPDATE accounts SET balance = balance + 100 WHERE id = 2
    option Transaction fails
        DB-->>App: ROLLBACK
    end
    App->>DB: COMMIT
    DB-->>App: OK
Try in Editor →

Autonumber

Automatically number each message for easy reference:

sequenceDiagram
    autonumber
    Alice->>Bob: Request
    Bob->>Charlie: Forward
    Charlie-->>Bob: Response
    Bob-->>Alice: Response
Try in Editor →

Real-World Example: Microservice Order Flow

sequenceDiagram
    autonumber
    actor Customer
    participant GW as API Gateway
    participant OS as Order Service
    participant IS as Inventory Service
    participant PS as Payment Service
    participant NS as Notification Service

    Customer->>+GW: POST /orders
    GW->>+OS: Create order
    OS->>+IS: Check stock
    IS-->>-OS: In stock

    OS->>+PS: Charge customer
    alt Payment success
        PS-->>-OS: Payment confirmed
        OS->>NS: Send confirmation email
        NS-->>OS: Queued
        OS-->>-GW: Order created (201)
        GW-->>-Customer: Order confirmation
    else Payment failed
        PS-->>OS: Payment declined
        OS->>IS: Release reservation
        OS-->>GW: Payment failed (402)
        GW-->>Customer: Error message
    end
Try in Editor →

Best Practices

  1. Declare participants explicitly to control the order they appear left-to-right.
  2. Use aliases for long service names — participant PS as Payment Service.
  3. Use activation bars to show processing duration — it makes timing clear.
  4. Add autonumber when you'll reference steps in documentation ("In step 3, the server validates...").
  5. Use alt/else for error handling flows — document both happy and sad paths.
  6. Keep it focused — one sequence diagram per use case. Don't try to show every possible flow in one diagram.
  7. Add notes for non-obvious details like "Token expires in 1 hour" or "Retries 3 times".

Common Pitfalls

  • Forgetting the closing end for loop/alt/opt/par blocks — each needs a matching end.
  • Too many participants — more than 6-7 makes the diagram too wide. Group related services.
  • Missing responses — every request should ideally have a response shown, even if it's async.

Conclusion

Sequence diagrams are essential for documenting how systems communicate. Mermaid's text-based approach means your diagrams stay in sync with your code, live in your repo, and are easy to update. Start with the basic arrow syntax, then add loops, alt blocks, and activation as needed.

Try it now in our free Mermaid Live Editor →

Try it now in our free Mermaid Live Editor →
← All Articles