# Sequence Diagram Type Use Cases: Visualizing Messages Over Time

> Explore sequence diagram use cases for visualizing messages over time. Understand request-response flows, protocol exchanges, API calls, and incident reconstructions.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: use-cases
- Published: 2026-08-21

---

**The sequence diagram type excels at visualizing messages over time between multiple actors, making it ideal for request-response flows, protocol exchanges, API call traces, and incident reconstructions.**

The `cathrynlavery/diagram-design` repository defines the **sequence diagram type** as a specialized visualization for temporal communication patterns. According to the source code, this diagram type captures the order, direction, and timing of interactions in a clear linear flow, explicitly documented in the repository's reference architecture.

## Core Use Cases for the Sequence Diagram Type

The definitive list of use cases resides in [`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md). These six scenarios leverage the type's unique ability to map chronological communication between distributed components.

### Request-Response Flows

**Request-response flows** represent the most common application, covering HTTP calls, RPCs, and general client-server exchanges. The diagram renders directional arrows showing both the invocation path and return messages between participants, making latency and synchronous dependencies immediately visible.

### Protocol Exchanges

**Protocol exchanges** require depicting sequential steps of handshakes or communication protocols. The strict time axis verifies that each party transmits the expected message at the correct stage, essential for validating TCP handshakes, TLS negotiations, or custom binary protocols.

### Multi-Actor Interactions Over Time

When **multiple actors interact over time**, the sequence diagram clarifies how several services or components communicate chronologically. Vertical **lifelines** visualize each participant's existence throughout the transaction, while horizontal arrows represent the actual message passing.

### API Call Traces

**API call traces** track invocation chains across microservices. This use case helps developers understand cascading dependencies and identify latency bottlenecks in distributed systems by showing the full chain of service-to-service calls.

### Incident Reconstructions

**Incident reconstructions** employ the diagram type to rebuild the exact sequence of events leading to system failures. The temporal layout aids root-cause analysis by revealing message order, timeout patterns, and race conditions that static logs cannot easily convey.

### Authentication and Token Refresh Paths

**Authentication flows with branching** model conditional logic such as token validation, refresh, or retry paths. The repository's [`example-sequence-oauth.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-sequence-oauth.html) demonstrates **combined fragments** (`alt`) handling these conditional branches, showing both the happy path and error handling within a single diagram.

## Repository Implementation and Visual Conventions

The [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) identifies the visual cue for this type as **"Messages over time"** (lines 44-45), reinforcing its purpose for temporal communication diagrams. The reference file [`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md) establishes the layout conventions, message kinds, and combined-fragment rules that govern these visualizations, including specifications for activation bars and color-coded arrows.

## Code Examples

The repository provides both inline markup and full HTML implementations demonstrating these use cases.

### Basic Mermaid Syntax

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Auth
    Client->>API: GET /resource
    API->>Auth: Validate token
    Auth-->>API: Token OK
    API-->>Client: 200 OK

```

### HTML Implementation with Branching

The shipped example [`skills/diagram-design/assets/example-sequence.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-sequence.html) illustrates a cold-cache article request with lifelines and activation bars. For conditional logic, [`skills/diagram-design/assets/example-sequence-oauth.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-sequence-oauth.html) demonstrates a bearer-call with an `alt` fragment for token-refresh branching, including colour-coded arrows that follow the conventions described in the reference file.

## Summary

- The sequence diagram type specializes in **messages over time** between multiple actors, as defined in `cathrynlavery/diagram-design`.
- Primary use cases include **request-response flows**, **protocol exchanges**, **multi-actor interactions**, **API call traces**, **incident reconstructions**, and **authentication paths**.
- Implementation conventions are codified in [`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md).
- The repository provides working HTML examples in [`example-sequence.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-sequence.html) (basic flows) and [`example-sequence-oauth.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-sequence-oauth.html) (conditional branching).
- **Combined fragments** (`alt`) support complex branching logic for error handling and token refresh scenarios.

## Frequently Asked Questions

### What is the primary purpose of the sequence diagram type?

The primary purpose is to visualize **messages over time** between multiple actors, showing the order, direction, and timing of interactions in a chronological linear flow. This temporal focus distinguishes it from structural diagrams that show static relationships.

### Where are the sequence diagram conventions defined in the repository?

Conventions are defined in [`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md), which specifies layout rules, message kinds, combined-fragment syntax, and the complete list of recommended use cases. The [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (lines 44-45) provides the high-level gallery description identifying the type as "Messages over time".

### Can sequence diagrams handle conditional logic like token refresh?

Yes. The repository includes [`skills/diagram-design/assets/example-sequence-oauth.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-sequence-oauth.html), which demonstrates **combined fragments** (`alt`) to model conditional branches such as token validation failures and refresh logic within the same diagram visualization.

### What file contains the basic sequence diagram example?

The file [`skills/diagram-design/assets/example-sequence.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-sequence.html) contains a minimal light-theme HTML example illustrating a basic cold-cache happy path with lifelines, activation bars, and synchronous message calls.