Mermaid Sequence Diagram

calendar Dec 12, 2024 · 3 min read · mermaid sequence diagram api interaction diagrams  ·
Share on: linkedin copy

Sequence diagrams show interactions between different components over time. Perfect for documenting API calls, system interactions, and message flows.

Use Case

Use sequence diagrams when you need to:

  • Document API interactions
  • Show message passing between components
  • Visualize request/response flows
  • Map out system communication patterns

Code

1```mermaid
2sequenceDiagram
3    participant A as Alice
4    participant B as Bob
5    
6    A->>B: Hello Bob!
7    B-->>A: Hi Alice!
8```

Result:

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

Explanation

  • participant - Define participants (optional, auto-detected)
  • ->> - Solid arrow (synchronous call)
  • -->> - Dashed arrow (asynchronous return)
  • ->>+ - Activate lifeline
  • -->>- - Deactivate lifeline

Examples

Example 1: API Request Flow

 1```mermaid
 2sequenceDiagram
 3    participant Client
 4    participant API
 5    participant Database
 6    
 7    Client->>+API: POST /api/data
 8    API->>+Database: INSERT query
 9    Database-->>-API: Success
10    API-->>-Client: 201 Created
11```

Result:

sequenceDiagram
    participant Client
    participant API
    participant Database
    
    Client->>+API: POST /api/data
    API->>+Database: INSERT query
    Database-->>-API: Success
    API-->>-Client: 201 Created

Example 2: With Loops and Alt

 1```mermaid
 2sequenceDiagram
 3    participant User
 4    participant System
 5    participant Cache
 6    participant DB
 7    
 8    User->>System: Request Data
 9    System->>Cache: Check Cache
10    
11    alt Cache Hit
12        Cache-->>System: Return Data
13    else Cache Miss
14        System->>DB: Query Database
15        DB-->>System: Return Data
16        System->>Cache: Update Cache
17    end
18    
19    System-->>User: Return Data
20```

Result:

sequenceDiagram
    participant User
    participant System
    participant Cache
    participant DB
    
    User->>System: Request Data
    System->>Cache: Check Cache
    
    alt Cache Hit
        Cache-->>System: Return Data
    else Cache Miss
        System->>DB: Query Database
        DB-->>System: Return Data
        System->>Cache: Update Cache
    end
    
    System-->>User: Return Data

Example 3: With Notes

 1```mermaid
 2sequenceDiagram
 3    participant A as Algorithm
 4    participant D as Data
 5    
 6    Note over A,D: Initialization Phase
 7    A->>D: Load Data
 8    D-->>A: Data Ready
 9    
10    Note right of A: Processing
11    loop For each item
12        A->>D: Process Item
13        D-->>A: Result
14    end
15    
16    Note over A: Complete
17```

Result:

sequenceDiagram
    participant A as Algorithm
    participant D as Data
    
    Note over A,D: Initialization Phase
    A->>D: Load Data
    D-->>A: Data Ready
    
    Note right of A: Processing
    loop For each item
        A->>D: Process Item
        D-->>A: Result
    end
    
    Note over A: Complete

Notes

  • Use participant X as Name for readable aliases
  • Note over A,B: Text spans multiple participants
  • Note left/right of A: Text for single participant notes
  • Supports loop, alt, opt, par blocks

Gotchas/Warnings

  • ⚠️ Arrow types: ->> (solid) vs -->> (dashed) - use consistently
  • ⚠️ Activation: + and - must be balanced
  • ⚠️ Participant order: Defined order determines left-to-right placement
  • ⚠️ Long text: Break long messages into multiple lines with <br/>

Related Snippets