Sequence Diagrams: Interactions Over Time

🔄 Flowcharts (Lesson 3) show what happens step by step. But when multiple systems interact — a user calling an API, the API calling a database, the database returning data — you need to see who talks to whom and when. That’s what sequence diagrams show.

When to Use Sequence Diagrams

Use sequence diagrams when the question is: “What messages get sent between these systems, and in what order?”

Common use cases:

• API request/response flows
• Microservice communication
• Authentication handshakes (OAuth, JWT)
• User interaction flows (frontend ↔ backend ↔ database)
• Third-party integration documentation

Your First Sequence Diagram

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database

    U->>A: POST /login
    A->>D: SELECT user WHERE email = ?
    D-->>A: User record
    A-->>U: JWT token

Four participants, four messages, and you can see the entire login flow in seconds. Let’s break down the syntax.

Participants

Declare participants at the top to control their order (left to right):

sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant S as Auth Service
    participant D as Database

The as keyword creates an alias — C is the ID you use in messages, Client is the display name. Without participant declarations, Mermaid auto-creates participants in the order they first appear.

Actors vs. participants: Use actor for people (shown as a stick figure) and participant for systems (shown as a box):

sequenceDiagram
    actor U as User
    participant A as API
    participant D as Database

Message Types

The solid/dashed distinction communicates whether the sender blocks and waits. This is crucial for understanding system behavior.

✅ Quick Check: In an OAuth flow, the browser redirects the user to Google’s login page. Is this a synchronous (-» ) or asynchronous (–» ) message? (It’s synchronous — the browser waits for Google’s response before continuing. The redirect blocks the flow until the user authenticates.)

Activation Boxes

Show when a participant is actively processing:

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>+S: Request
    S->>S: Process
    S-->>-C: Response

The + activates (starts the box), - deactivates (ends the box). This shows the server is busy between receiving the request and sending the response.

Control Flow: alt, opt, loop, par

Sequence diagrams handle conditional and repeating behavior:

Alternatives (if/else)

sequenceDiagram
    U->>A: Login request
    A->>D: Check credentials
    alt Valid credentials
        D-->>A: User found
        A-->>U: 200 OK + token
    else Invalid credentials
        D-->>A: Not found
        A-->>U: 401 Unauthorized
    end

Optional (if without else)

sequenceDiagram
    U->>A: Request data
    opt Cache available
        A-->>U: Return cached data
    end
    A->>D: Query database

Loops

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: Request
    loop Retry up to 3 times
        S->>S: Process
        S-->>C: Error 500
        C->>S: Retry request
    end
    S-->>C: Success 200

Parallel

sequenceDiagram
    par Send notifications
        A-)Email: Send email
    and
        A-)SMS: Send SMS
    and
        A-)Push: Send push notification
    end

Notes

Add context without cluttering the message flow:

sequenceDiagram
    U->>A: POST /payment
    Note right of A: Validate payment details
    A->>P: Charge card
    Note over U,P: Encrypted connection
    P-->>A: Confirmation

Note right of, Note left of, Note over — use these to explain business rules, security details, or implementation notes.

✅ Quick Check: You’re documenting a webhook system where your API sends an event to a third-party service and doesn’t wait for a response. Which arrow type would you use? (The async fire-and-forget arrow: A-)ThirdParty: webhook event. The open arrowhead without dashes signals that the sender continues without waiting.)

Real-World Example: OAuth 2.0 Flow

sequenceDiagram
    actor U as User
    participant App as Web App
    participant Auth as Auth Server
    participant API as Resource API

    U->>App: Click "Login with Google"
    App->>Auth: Redirect to /authorize
    Auth->>U: Show login form
    U->>Auth: Enter credentials
    Auth-->>App: Authorization code
    App->>Auth: Exchange code for token
    Auth-->>App: Access token + refresh token
    App->>API: Request with access token
    API-->>App: Protected resource
    App-->>U: Display data

This diagram communicates what might take a full page of prose. Any developer who reads it understands the OAuth flow immediately.

Key Takeaways

• Sequence diagrams show who talks to whom and in what order — perfect for APIs, microservices, and authentication flows
• Use actor for people and participant for systems
• Solid arrows (->>) = synchronous (sender waits); dashed arrows (-->>) = response or async
• Control flow constructs: alt/else for conditionals, loop for repetition, par for parallel messages, opt for optional
• Activation boxes (+/-) show when a participant is processing
• Notes add context without cluttering the message flow

Up Next

In Lesson 5, we’ll cover the remaining diagram types: entity-relationship diagrams for databases, state diagrams for workflows, Gantt charts for timelines, and a quick tour of class diagrams, mind maps, and pie charts.