What is a Sequence Diagram?

A sequence diagram is a type of UML (Unified Modeling Language) diagram that shows how objects or components interact over time. It illustrates the sequence of messages exchanged between participants in a system, making it one of the most useful tools for designing APIs, microservices architectures, authentication flows, and business processes.

Sequence diagrams are widely used in software engineering to model:

• API request/response flows — visualize how a client, server, and database communicate
• Authentication workflows — map out OAuth, JWT, or session-based login sequences
• Microservice interactions — document how services discover, call, and respond to each other
• User journeys — show how a user interacts with UI components and backend systems
• Protocol handshakes — illustrate WebSocket upgrades, TLS negotiations, or message queuing

Why Use Mermaid for Sequence Diagrams?

Mermaid is a JavaScript-based diagramming and charting tool that lets you define diagrams using plain text. Instead of dragging and dropping shapes in a visual editor, you write declarative syntax that gets rendered into SVG. This approach offers several advantages:

Version control friendly — Mermaid diagram definitions are plain text, making them easy to review in pull requests, store in git, and diff across versions. No more binary diagram files that are impossible to merge.

Developer-first workflow — Write diagram syntax in your editor, documentation, or issue tracker. Mermaid is supported natively on GitHub, GitLab, and Notion, so your diagrams render wherever your code lives.

Fast iteration — Change a participant name or message in seconds. No need to reposition arrows or resize boxes. The layout engine handles positioning automatically.

Privacy-preserving — Like all LangStop tools, the Mermaid Sequence Diagram editor runs entirely in your browser. Your diagram data never touches a server.

Mermaid Sequence Diagram Syntax

Mermaid sequence diagrams use a simple, readable syntax. Here are the key building blocks:

Participants

Participants are the actors in your diagram. Define them at the top:

sequenceDiagram
    participant Alice
    participant Bob
    participant Server

Messages

Messages show communication between participants:

sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!

Arrow types:

• -> — solid line without arrow
• ->> — solid line with arrow
• --> — dashed line without arrow
• -->> — dashed line with arrow
• ->x — solid line with cross at end
• --x — dashed line with cross

Activations and Deactivations

Show when a participant is active (holding a thread or processing):

sequenceDiagram
    Alice->>+Bob: Request
    Bob-->>-Alice: Response

The + after the participant name activates it, and - deactivates it.

Notes

Add explanatory notes beside participants:

sequenceDiagram
    Alice->>Bob: Hello
    Note right of Bob: Thinking...
    Bob-->>Alice: Hi!

Loops, Alt, and Opt

Model conditional and repeated behavior:

sequenceDiagram
    Alice->>Bob: Check status
    alt Success
        Bob-->>Alice: OK
    else Failure
        Bob-->>Alice: Error
    end

Parallel Actions

Show concurrent operations:

sequenceDiagram
    par Alice calls Bob
        Alice->>Bob: Call
    and Alice calls Charlie
        Alice->>Charlie: Call
    end

Best Practices for Sequence Diagrams

Keep participants meaningful — Name participants after their role (User, API Gateway, Database) rather than implementation details.

Show the happy path first — Start with the successful flow, then add error cases using alt/else blocks.

Use activation boxes — They make it visually clear which component is actively processing at each step.

Limit diagram complexity — If a diagram has more than 10 participants or 30 messages, consider splitting it into multiple focused diagrams.

Add notes for clarity — Use Note right of or Note over to explain non-obvious behavior without cluttering the message flow.

Common Sequence Diagram Patterns

Authentication Flow

A typical OAuth2 authorization code flow:

sequenceDiagram
    participant User
    participant App
    participant AuthServer
    participant API
 
    User->>App: Login
    App->>AuthServer: Authorization Request
    AuthServer-->>User: Login Page
    User->>AuthServer: Credentials
    AuthServer-->>App: Authorization Code
    App->>AuthServer: Code + Client Secret
    AuthServer-->>App: Access Token
    App->>API: Request + Token
    API-->>App: Response
    App-->>User: Success

API Request Flow

A typical REST API call with database lookup:

sequenceDiagram
    participant Client
    participant API
    participant Cache
    participant DB
 
    Client->>API: GET /users/123
    API->>Cache: Check cache
    alt Cache hit
        Cache-->>API: Cached data
    else Cache miss
        API->>DB: SELECT * FROM users
        DB-->>API: User data
        API->>Cache: Set cache
    end
    API-->>Client: 200 OK + Data

WebSocket Connection

WebSocket upgrade and messaging:

sequenceDiagram
    participant Client
    participant Server
    participant PubSub
 
    Client->>Server: HTTP Upgrade Request
    Server-->>Client: 101 Switching Protocols
    Note over Client,Server: WebSocket open
    Client->>Server: Subscribe: channel_1
    Server->>PubSub: Register subscription
    PubSub-->>Server: New message
    Server-->>Client: Message payload
    Client->>Server: Unsubscribe
    Server->>PubSub: Remove subscription
    Client->>Server: Close frame
    Server-->>Client: Close frame
    Note over Client,Server: Connection closed

Why Choose LangStop's Mermaid Sequence Diagram Tool?

Free and private — No signup, no data uploads, no limits. Everything runs in your browser.

Developer-focused — Clean interface with syntax examples, error highlighting, and SVG export. Designed for engineers who need to create diagrams quickly.

Export ready — Download your diagrams as high-quality SVG for documentation, presentations, and pull requests.

Zero dependencies — Besides the rendering itself, no frameworks or libraries are loaded. The tool is self-contained and works offline once loaded.

Accessible — Keyboard navigable, screen reader friendly, and works on mobile devices.

Frequently Asked Questions

Is my data sent to a server when using this tool?

No. The Mermaid Sequence Diagram editor runs entirely in your browser. Your diagram syntax is processed locally using the Mermaid JavaScript library. No data is transmitted to any server.

Can I use this tool offline?

Yes. Once the page is loaded, the core functionality works without an internet connection. The Mermaid rendering engine runs entirely client-side.

What version of Mermaid does this tool use?

This tool uses Mermaid 11.x, the latest stable version with full support for sequence diagram syntax, including activations, notes, loops, alt/else blocks, parallel actions, and custom styling.

Can I export my diagram as an image?

Yes. You can download your sequence diagram as an SVG file, which can be opened in any vector graphics editor or embedded directly in documentation.

What's the difference between Mermaid and traditional UML tools?

Mermaid uses a text-based syntax that's version-control friendly and easy to integrate into documentation workflows. Traditional UML tools typically use visual drag-and-drop interfaces that generate proprietary file formats. Mermaid trades some visual polish for speed, simplicity, and developer-friendliness.

Are there any limits on diagram size?

The tool can handle large diagrams, but very complex diagrams (50+ participants or 200+ messages) may cause performance issues. For large diagrams, consider splitting them into multiple focused views. This is a browser memory limitation, not a tool limitation.