Mermaid Sequence Diagram Guide: From Beginner to Pro

Sequence diagrams are one of the most powerful tools in a developer's toolkit. They help you visualize how different parts of a system interact over time — whether it's an API call chain, a microservice orchestration, or a user authentication flow.

In this guide, we'll walk through everything you need to know about creating sequence diagrams with Mermaid, from basic syntax to advanced patterns.

Why Mermaid for Sequence Diagrams?

Mermaid's sequence diagram syntax is incredibly readable. Here's a simple login flow:

sequenceDiagram
    User->>Frontend: Enter credentials
    Frontend->>API: POST /login
    API->>Database: Verify credentials
    Database-->>API: User found
    API-->>Frontend: JWT token
    Frontend-->>User: Redirect to dashboard

That's it — five lines of code, and you have a clear visualization of the entire login flow.

Basic Syntax

Participants

Every sequence diagram starts with participants. Each participant represents an actor, service, or component in your system.

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

    U->>F: Click login
    F->>B: POST /auth/login
    B->>D: SELECT user

Use participant to give your actors meaningful aliases. Without an alias, Mermaid uses the participant name directly.

Messages

Mermaid supports four types of message arrows:

Choosing the right arrow makes your diagram immediately clearer. Use solid lines for requests and dashed lines for responses:

sequenceDiagram
    Client->>Server: GET /users
    Server-->>Client: 200 OK [User data]
    Client->>Server: POST /users
    Server-->>Client: 201 Created

Activations

Activations show when a participant is "active" — processing a request or doing work. Create them with activate and deactivate, or use the shorthand +/-:

sequenceDiagram
    Client->>+Server: POST /orders
    Server->>+Database: INSERT order
    Database-->>-Server: Order created
    Server-->>-Client: 201 Created

The + activates the target, and - deactivates it. This visualizes exactly how long each component is busy.

Advanced Patterns

Notes

Notes add context or constraints to your diagram:

sequenceDiagram
    ServiceA->>ServiceB: POST /process
    Note right of ServiceB: Validates input
    ServiceB->>ServiceC: Forward request
    Note over ServiceA,ServiceC: Idempotency key: req-123

Loops, Alt, and Opt

Real-world interactions rarely follow a straight line. Mermaid supports conditional logic:

sequenceDiagram
    Client->>+API: Request with auth token
    alt valid token
        API->>+DB: Query data
        DB-->>-API: Results
        API-->>Client: 200 OK
    else invalid token
        API-->>Client: 401 Unauthorized
    end

Parallel Execution

When multiple independent calls happen simultaneously:

sequenceDiagram
    Client->>+Gateway: Place order
    par Parallel processing
        Gateway->>+Inventory: Check stock
        Inventory-->>-Gateway: In stock
    and
        Gateway->>+Payment: Charge card
        Payment-->>-Gateway: Success
    and
        Gateway->>+Notification: Send email
        Notification-->>-Gateway: Queued
    end
    Gateway-->>-Client: Order confirmed

Best Practices

1. Keep It Focused

Don't try to diagram your entire system in one chart. A good sequence diagram tells one story:

• A single API request lifecycle
• One microservice orchestration
• One user interaction flow

2. Use Descriptive Participant Names

sequenceDiagram
    participant PaymentGateway
    participant FraudDetector
    participant OrderService

This is immediately clear to anyone reading the diagram.

3. Add Context with Notes

Notes bridge the gap between the visual flow and the business rules:

sequenceDiagram
    User->>Checkout: Submit order
    Checkout->>PaymentGateway: Authorize payment
    Note right of PaymentGateway: Max 3 retry attempts

4. Test Early, Iterate Often

Use the OnUML Editor to create and preview your diagrams in real-time. The live preview helps you catch layout issues before sharing.

Conclusion

Mermaid sequence diagrams are a lightweight yet powerful way to document system interactions. They're version-control friendly (plain text!), render beautifully in GitHub, and are easy to learn.

Start with the basic syntax above, experiment in the OnUML Editor, and you'll be creating professional diagrams in minutes.

Next in this series: Mermaid Flowchart Guide: Syntax, Examples & Best Practices