mermaid-sequence-diagrams

Create interaction and message flow diagrams with Mermaid showing communication between actors, services, and components over time

Mermaid Sequence Diagrams

Scope: Interaction and message flow visualization with Mermaid.js Lines: ~350 Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)

When to Use This Skill

Activate this skill when:

Core Concepts

Concept 1: Participants and Actors

Basic participant definition:

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B->>A: Hi Alice!

Participant types:

sequenceDiagram
    actor User
    participant API as API Gateway
    participant Auth as Auth Service
    database DB as PostgreSQL
    queue Q as Message Queue

    User->>API: POST /login
    API->>Auth: Verify credentials
    Auth->>DB: Query user
    DB-->>Auth: User data
    Auth-->>API: Token
    API->>Q: Log event
    API-->>User: 200 OK + Token

Participant ordering:

sequenceDiagram
    %% Define order explicitly
    participant C as Client
    participant API
    participant Cache
    participant DB

    C->>API: Request
    API->>Cache: Check cache
    alt Cache miss
        API->>DB: Query
        DB-->>API: Data
        API->>Cache: Store
    end
    API-->>C: Response

Concept 2: Message Arrow Types

Arrow styles and meanings:

sequenceDiagram
    participant A
    participant B

    A->>B: Solid line with arrow (synchronous)
    A-->>B: Dotted line with arrow (async/response)
    A->B: Solid line without arrow (simple message)
    A-->B: Dotted line without arrow
    A-xB: Solid line with X (failed/rejected)
    A--xB: Dotted line with X
    A-)B: Solid line with open arrow (async)
    A--)B: Dotted line with open arrow

Semantic usage:

sequenceDiagram
    participant Client
    participant Server
    participant DB

    Client->>Server: Synchronous request
    activate Server
    Server->>DB: Query (sync)
    activate DB
    DB-->>Server: Result (response)
    deactivate DB
    Server-)Client: Async notification
    Server-->>Client: Response (reply)
    deactivate Server

    Client-xServer: Failed request

Concept 3: Activation Boxes

Manual activation:

sequenceDiagram
    participant A
    participant B

    A->>B: Request
    activate B
    B->>B: Process internally
    B-->>A: Response
    deactivate B

Shorthand with +/-:

sequenceDiagram
    participant Client
    participant API
    participant Service

    Client->>+API: Request
    API->>+Service: Forward
    Service-->>-API: Response
    API-->>-Client: Result

Nested activations:

sequenceDiagram
    participant A
    participant B
    participant C

    A->>+B: Start
    B->>+C: Call helper
    C-->>-B: Helper result
    B->>+C: Another call
    C-->>-B: Second result
    B-->>-A: Final result

Concept 4: Control Flow Blocks

Alternatives (if/else):

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: Request user
    API->>DB: Query

    alt User found
        DB-->>API: User data
        API-->>Client: 200 OK
    else User not found
        DB-->>API: Not found
        API-->>Client: 404 Not Found
    else Database error
        DB--xAPI: Error
        API-->>Client: 500 Server Error
    end

Optional block:

sequenceDiagram
    participant User
    participant App
    participant Analytics

    User->>App: Perform action
    App->>App: Process

    opt Analytics enabled
        App-)Analytics: Track event
    end

    App-->>User: Success

Loop block:

sequenceDiagram
    participant Client
    participant API
    participant Queue

    loop Until success or max retries
        Client->>API: Poll for result
        API->>Queue: Check status

        alt Ready
            Queue-->>API: Result
            API-->>Client: 200 + Data
        else Not ready
            Queue-->>API: Pending
            API-->>Client: 202 Accepted
        end
    end

Parallel blocks:

sequenceDiagram
    participant Client
    participant Gateway
    participant ServiceA
    participant ServiceB
    participant ServiceC

    Client->>Gateway: Request

    par Call ServiceA
        Gateway->>ServiceA: Request
        ServiceA-->>Gateway: ResponseA
    and Call ServiceB
        Gateway->>ServiceB: Request
        ServiceB-->>Gateway: ResponseB
    and Call ServiceC
        Gateway->>ServiceC: Request
        ServiceC-->>Gateway: ResponseC
    end

    Gateway-->>Client: Aggregated result

Critical sections:

sequenceDiagram
    participant P1 as Process 1
    participant Resource
    participant P2 as Process 2

    critical Acquire lock
        P1->>Resource: Lock
        Resource-->>P1: Locked
        P1->>Resource: Read/Write
    option Lock timeout
        Resource--xP1: Timeout
    end

    P1->>Resource: Unlock

Concept 5: Notes and Comments

Note positioning:

sequenceDiagram
    participant A
    participant B
    participant C

    Note left of A: Client initiates
    A->>B: Request
    Note right of B: Server validates
    B->>C: Forward
    Note over C: Database query
    C-->>B: Result
    Note over A,B: Response path
    B-->>A: Response

Multi-line notes:

sequenceDiagram
    participant API
    participant DB

    Note over API,DB: Transaction begins<br/>Multiple operations<br/>Must complete atomically

    API->>DB: BEGIN
    API->>DB: INSERT
    API->>DB: UPDATE
    API->>DB: COMMIT

Comments:

sequenceDiagram
    %% This is a comment explaining the flow
    participant A
    participant B

    %% Main interaction
    A->>B: Message

    %% TODO: Add error handling

Common Patterns

Pattern 1: RESTful API Request/Response

sequenceDiagram
    actor Client
    participant Gateway as API Gateway
    participant Auth as Auth Service
    participant API as User Service
    database DB as PostgreSQL

    Client->>+Gateway: POST /users/login
    Note over Client,Gateway: HTTPS with credentials

    Gateway->>+Auth: Verify JWT
    alt Valid token
        Auth-->>-Gateway: Claims
        Gateway->>+API: GET /users/{id}
        API->>+DB: SELECT * FROM users
        DB-->>-API: User record
        API-->>-Gateway: 200 OK + User data
        Gateway-->>-Client: 200 OK
    else Invalid token
        Auth-->>-Gateway: Unauthorized
        Gateway-->>Client: 401 Unauthorized
    end

Pattern 2: Microservice Communication

sequenceDiagram
    participant Order as Order Service
    participant Inventory as Inventory Service
    participant Payment as Payment Service
    participant Shipping as Shipping Service
    queue EventBus as Event Bus

    Order->>+Inventory: Reserve items
    Inventory-->>-Order: Reserved

    Order->>+Payment: Charge customer
    alt Payment success
        Payment-->>-Order: Success
        Order-)EventBus: OrderPaid event
        EventBus-)Inventory: Confirm reservation
        EventBus-)Shipping: Initiate shipment

        par Ship order
            Shipping->>Shipping: Create shipment
        and Update inventory
            Inventory->>Inventory: Decrement stock
        end
    else Payment failed
        Payment-->>-Order: Failed
        Order->>Inventory: Release reservation
        Order-->>Order: Cancel order
    end

Pattern 3: Retry with Exponential Backoff

sequenceDiagram
    participant Client
    participant API
    participant Service

    loop Retry up to 3 times
        Client->>+API: Request
        API->>+Service: Call external API

        alt Success
            Service-->>-API: 200 OK
            API-->>-Client: Success
        else Failure
            Service--xAPI: 503 Service Unavailable
            API-->>-Client: 503 + Retry-After
            Note over Client: Wait exponentially<br/>(1s, 2s, 4s)
        end
    end

    alt Max retries exceeded
        Client->>Client: Log failure
        Note over Client: Circuit breaker opens
    end

Best Practices

1. Clear Participant Naming

sequenceDiagram
    %% Good: Descriptive names
    actor User
    participant WebApp as Web Application
    participant AuthAPI as Authentication API
    database UserDB as User Database

    %% Bad: Cryptic abbreviations
    participant A
    participant B
    participant C

2. Use Activation Appropriately

sequenceDiagram
    participant A
    participant B

    %% Shows that B is processing
    A->>+B: Request
    B->>B: Long process
    B-->>-A: Response

    %% Not needed for simple pass-through
    A->>B: Quick message
    B-->>A: Quick reply

3. Group Related Interactions

sequenceDiagram
    box User Layer
        actor User
        participant UI
    end

    box Application Layer
        participant API
        participant Service
    end

    box Data Layer
        database DB
        database Cache
    end

    User->>UI: Click button
    UI->>API: POST /action
    API->>Service: Process
    Service->>Cache: Check
    Service->>DB: Query

4. Label Meaningful Responses

sequenceDiagram
    participant A
    participant B

    %% Good: Shows what's returned
    A->>B: GET /user/123
    B-->>A: 200 OK + {id, name, email}

    %% Bad: Generic response
    A->>B: Request
    B-->>A: Response

Anti-Patterns

❌ Too Many Participants

Creates visual clutter, hard to follow:

sequenceDiagram
    participant A
    participant B
    participant C
    participant D
    participant E
    participant F
    participant G

Solution: Group related participants or split into multiple diagrams

❌ Missing Activations

Can't tell when services are actively processing:

sequenceDiagram
    A->>B: Start long process
    B->>C: Sub-task
    C-->>B: Done
    B-->>A: Complete

✅ Better:

sequenceDiagram
    A->>+B: Start long process
    B->>+C: Sub-task
    C-->>-B: Done
    B-->>-A: Complete

❌ Unlabeled Decision Points

sequenceDiagram
    A->>B: Request
    alt
        B-->>A: Response1
    else
        B-->>A: Response2
    end

✅ Better:

sequenceDiagram
    A->>B: Request
    alt Valid input
        B-->>A: 200 OK
    else Invalid input
        B-->>A: 400 Bad Request
    end

Integration with Other Diagrams

Related Skills

Resources