Mermaid Sequence Diagram

mermaidCopy

sequenceDiagram
    autonumber
    actor U as User
    participant W as Web App
    participant A as Auth API
    participant D as Database
    U->>W: Submit login form
    W->>A: POST /login
    A->>D: Find user by email
    D-->>A: User record
    alt password valid
        A-->>W: 200 + session token
        W-->>U: Redirect to dashboard
    else invalid
        A-->>W: 401 Unauthorized
        W-->>U: Show error
    end

Open in the live editor

Sequence diagrams show the order in which participants exchange messages. They are the go-to diagram for API calls, authentication handshakes, microservice interactions and any flow where timing matters.

Mermaid sequence diagrams read almost like a script: each line is one message from one participant to another. Mermaid handles lifelines, arrow alignment and spacing, and you get blocks for loops, alternatives, optional steps and parallel work.

When to use a sequence diagram

• Documenting REST and GraphQL API request/response flows
• Explaining OAuth, SSO and other authentication handshakes
• Designing event-driven and microservice interactions
• Debugging race conditions by laying out message order

Sequence Diagram syntax reference

Sequence Diagram examples

mermaidCopy

sequenceDiagram
    participant C as Client
    participant S as Service
    participant Q as Queue
    C->>+S: Create job
    S->>Q: Enqueue
    loop Every 5s until done
        C->>S: GET /status
        S-->>C: pending
    end
    S-->>-C: completed

Open in the live editor

mermaidCopy

sequenceDiagram
    participant G as API Gateway
    participant U as Users
    participant O as Orders
    participant R as Recommendations
    G->>U: Get profile
    par fetch in parallel
        G->>O: Recent orders
    and
        G->>R: Suggestions
    end
    O-->>G: orders
    R-->>G: items
    Note over G: Merge and respond

Open in the live editor

Tips and best practices

• Declare participants up front to control their left-to-right order instead of relying on first mention.
• Use solid arrows (->>) for requests and dotted arrows (-->>) for responses to make the flow scannable.
• Turn on autonumber for diagrams that will be discussed in reviews so people can reference steps.
• Keep messages short; push details into notes so the diagram stays readable.

Generate a sequence diagram with AI

Not sure where to start? Describe what you need and the AI sequence diagram generator writes the Mermaid code for you. Try prompts like:

• “OAuth 2.0 authorization code flow with PKCE”
• “Checkout with payment provider webhook confirmation”
• “Chat message delivery with read receipts”

Sequence Diagram templates