How to Create Sequence Diagrams in Confluence (Mermaid Examples)

Sequence diagrams are one of the most practical tools in a software team's documentation toolkit. They show how objects, services, or actors interact over time, making them ideal for documenting API flows, authentication processes, microservice choreography, and error-handling logic. If your team uses Confluence for documentation, embedding sequence diagrams directly on your pages keeps architecture docs alongside everything else your team needs.

In this tutorial, you will learn how to create sequence diagrams in Confluence using Mermaid syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the result immediately.

Why Sequence Diagrams in Confluence?

Teams choose sequence diagrams when they need to show who talks to whom, and in what order. Unlike flowcharts that emphasize decision branches, sequence diagrams focus on the temporal flow of messages between participants. This makes them especially useful for:

• Documenting API integrations so frontend and backend engineers stay aligned on request and response patterns
• Onboarding new engineers with visual walkthroughs of how a login, checkout, or data-sync process works end to end
• Design reviews where the team needs to agree on service boundaries and message contracts before writing code
• Incident post-mortems that trace the exact path a failed request took through the system

Confluence is where most of this context already lives: runbooks, design docs, sprint retros, and architecture decision records. Adding rendered sequence diagrams directly on those pages eliminates the friction of linking out to external diagramming tools or attaching exported images that go stale the moment the code changes.

Mermaid is the most popular text-to-diagram language, and with Mermaid Plus for Confluence you get a first-class editing experience right inside the Confluence editor.

Step-by-Step: Create Your First Sequence Diagram

Follow these steps to go from a blank Confluence page to a fully rendered sequence diagram.

Step 1 — Install Mermaid Plus for Confluence

Head to the Atlassian Marketplace and search for Mermaid Plus for Confluence. Click Get App and follow the installation prompts. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance.

If your organization pre-approves apps, check with your Confluence admin first. The app supports Confluence Cloud and Confluence Data Center.

Step 2 — Insert the Mermaid Macro

Open any Confluence page in edit mode. Type /mermaid in the editor and select the Mermaid Plus macro from the dropdown. A code editor panel appears where you can write Mermaid syntax.

Step 3 — Write the sequenceDiagram Header

Start every sequence diagram with the sequenceDiagram keyword. Then declare your participants:

sequenceDiagram
    participant A as Alice
    participant B as Bob

The participant keyword defines who appears on the diagram. The as keyword lets you use a short alias in the code while displaying a friendlier name in the rendered diagram.

Step 4 — Add Message Arrows

Messages are the core of any sequence diagram. Use arrow operators to show communication between participants:

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello, can you help?
    B-->>A: Sure, what do you need?

The ->> operator draws a solid arrow with a label. The -->> operator draws a dashed arrow, which is conventionally used for responses or asynchronous messages.

Step 5 — Save and Publish

Preview the diagram inside the macro editor to verify it renders correctly. When you are happy with the result, click Save on the macro, then Publish the Confluence page. The diagram is now part of your living documentation.

Mermaid Sequence Diagram Syntax Reference

Here is a quick-reference table for the most commonly used sequence diagram elements. Bookmark this section and come back to it whenever you need a syntax reminder.

Element	Syntax	Description
Solid arrow	A->>B: Message	Synchronous request or direct message
Dashed arrow	A-->>B: Message	Response, return value, or async message
Open arrow (solid)	A->B: Message	Arrow without arrowhead fill
Open arrow (dashed)	A-->B: Message	Dashed arrow without arrowhead fill
Participant	participant A as Alice	Declare a named participant with an alias
Actor	actor User	Stick-figure actor instead of a box
Note (left)	Note left of A: Text	Note to the left of a participant
Note (right)	Note right of B: Text	Note to the right of a participant
Note (over)	Note over A,B: Text	Note spanning multiple participants
Alt/Else block	alt Condition ... else ... end	Conditional branching
Loop block	loop Description ... end	Repeated iteration
Opt block	opt Condition ... end	Optional step
Par block	par ... and ... end	Parallel execution
Activate	activate A	Show activation bar on participant
Deactivate	deactivate A	Remove activation bar
Auto-number	autonumber	Number messages automatically
Comment	%% This is a comment	Inline comment, not rendered

5 Copy-Paste Sequence Diagram Examples

Below are five practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world scenario.

Example 1 — User Login Flow

This diagram shows a typical username/password login with a JWT token response. It covers the happy path and a failed-login branch.

sequenceDiagram
    autonumber
    actor User
    participant FE as Frontend App
    participant API as Auth Service
    participant DB as User Database
    participant Cache as Token Cache

    User->>FE: Enter credentials
    FE->>API: POST /auth/login {email, password}
    API->>DB: SELECT user WHERE email = ?
    DB-->>API: User record

    alt Valid credentials
        API->>API: Verify password hash
        API->>Cache: Store refresh token
        API-->>FE: 200 {access_token, refresh_token}
        FE-->>User: Redirect to dashboard
    else Invalid credentials
        API-->>FE: 401 Unauthorized
        FE-->>User: Show error message
    end

Use this diagram as a starting point for your own auth documentation. Add participants for SSO providers, multi-factor authentication services, or rate-limiting middleware as your architecture requires.

Example 2 — API Request/Response

A clean request-response pattern showing a REST API call with pagination. This pattern is useful for documenting public APIs that third-party developers consume.

sequenceDiagram
    autonumber
    participant Client as API Client
    participant GW as API Gateway
    participant SVC as Product Service
    participant DB as Database

    Client->>GW: GET /products?page=2&limit=20
    GW->>GW: Validate API key & rate limit
    GW->>SVC: Forward request

    SVC->>DB: SELECT products OFFSET 20 LIMIT 20
    DB-->>SVC: Result set (20 rows)

    SVC->>SVC: Map to DTOs
    SVC-->>GW: 200 {data, pagination: {page, total}}
    GW-->>Client: JSON response

    Note over Client,GW: Retry on 429 or 503

Notice the Note over Client,GW spanning two participants. Use spanning notes to annotate cross-cutting concerns like retry policies or SLA boundaries.

Example 3 — Microservice Communication

Microservice architectures involve chains of service-to-service calls. This example models an e-commerce order-placement flow with synchronous calls and an asynchronous event emission.

sequenceDiagram
    autonumber
    participant Client
    participant OrderSvc as Order Service
    participant InventorySvc as Inventory Service
    participant PaymentSvc as Payment Service
    participant EventBus as Event Bus
    participant NotifySvc as Notification Service

    Client->>OrderSvc: POST /orders
    activate OrderSvc

    OrderSvc->>InventorySvc: POST /inventory/reserve
    activate InventorySvc
    InventorySvc-->>OrderSvc: 200 {reservation_id}
    deactivate InventorySvc

    OrderSvc->>PaymentSvc: POST /payments/charge
    activate PaymentSvc

    alt Payment succeeds
        PaymentSvc-->>OrderSvc: 200 {charge_id}
        deactivate PaymentSvc
        OrderSvc->>EventBus: publish order.created
        EventBus-->>NotifySvc: deliver event
        NotifySvc->>NotifySvc: Send confirmation email
        OrderSvc-->>Client: 201 {order_id, status: confirmed}
    else Payment fails
        PaymentSvc-->>OrderSvc: 402 Payment declined
        deactivate PaymentSvc
        OrderSvc->>InventorySvc: POST /inventory/release
        OrderSvc-->>Client: 402 {error: payment_declined}
    end

    deactivate OrderSvc

The activate and deactivate keywords render the vertical activation bars that show when each service is actively processing a request. This visual cue helps readers see which services are waiting and which are working at any point in the flow.

Example 4 — Database Transaction

This diagram illustrates a database transaction with a rollback on failure. It is useful for documenting data-integrity requirements in financial or inventory systems.

sequenceDiagram
    autonumber
    participant App as Application
    participant DB as Database

    App->>DB: BEGIN TRANSACTION
    activate DB

    App->>DB: UPDATE accounts SET balance = balance - 100 WHERE id = 42
    DB-->>App: 1 row updated

    App->>DB: UPDATE accounts SET balance = balance + 100 WHERE id = 99
    DB-->>App: 1 row updated

    App->>DB: INSERT INTO transfers (from, to, amount) VALUES (42, 99, 100)
    DB-->>App: 1 row inserted

    alt All statements succeed
        App->>DB: COMMIT
        DB-->>App: Transaction committed
    else Any statement fails
        App->>DB: ROLLBACK
        DB-->>App: Transaction rolled back
        Note right of App: No partial writes persisted
    end

    deactivate DB

Example 5 — Error Handling Flow

Error-handling patterns are notoriously difficult to describe in prose. A sequence diagram makes the retry-and-circuit-breaker pattern immediately clear.

sequenceDiagram
    autonumber
    participant Client
    participant Retry as Retry Middleware
    participant CB as Circuit Breaker
    participant Service as Downstream Service

    Client->>Retry: Send request
    Retry->>CB: Forward request

    alt Service is healthy
        CB->>Service: Proxy request
        Service-->>CB: 200 OK
        CB-->>Retry: 200 OK
        Retry-->>Client: Success response
    else Service returns 5xx
        CB->>Service: Proxy request
        Service-->>CB: 503 Service Unavailable
        Note over CB: Record failure, increment count

        loop Retry up to 3 times with backoff
            Retry->>CB: Retry request
            CB->>Service: Proxy request
            Service-->>CB: Response
        end

        alt Retry succeeds
            CB-->>Retry: 200 OK
            Retry-->>Client: Success response
        else All retries exhausted
            CB->>CB: Open circuit
            CB-->>Retry: Circuit open error
            Retry-->>Client: 503 with fallback response
        end
    end

Tips for Complex Sequence Diagrams

As your diagrams grow beyond five or six participants, readability can suffer. These tips help you keep large diagrams manageable.

Use Alt and Else Blocks for Conditional Logic

Wrap branching paths in alt/else/end blocks instead of drawing every possible combination linearly. This keeps the main flow visible and tucks edge cases into clearly labeled sections.

alt Order is in stock
    Inventory-->>Order: Reserve items
else Order is out of stock
    Inventory-->>Order: Backorder items
end

Add Loops for Retry Logic and Polling

The loop keyword draws a labeled box around repeated steps. Use it for retry patterns, polling intervals, or batch processing loops.

loop Every 30 seconds
    Agent->>Server: GET /status
    Server-->>Agent: 200 {status: pending}
end

Annotate with Notes Sparingly

Notes are helpful for explaining non-obvious business rules, but overusing them clutters the diagram. A good rule of thumb is one note per major section of the diagram. Place notes on the side with the most white space to avoid overlapping arrows.

Auto-Number Messages

Add autonumber on the line immediately after sequenceDiagram. This numbers every message sequentially, which makes it easy to reference specific steps in a design review or Slack conversation ("let's talk about step 7 in the login diagram").

Keep Participant Names Short

Long participant names squeeze the horizontal space available for arrows and labels. Use the participant X as Long Name pattern so the code remains readable while the rendered diagram stays compact.

Break Large Diagrams into Smaller Ones

If a single diagram exceeds 20 to 25 messages, consider splitting it into two or more diagrams, each covering a distinct phase of the interaction. Link them together on the Confluence page with a brief prose explanation of what each diagram covers.

Use Styling for Emphasis

Mermaid supports inline styling with the style keyword. You can highlight critical paths or error states by changing the background color of specific participants:

style OrderSvc fill:#ffcccc,stroke:#ff0000

Apply styling judiciously. One or two highlighted participants draw attention; ten highlighted participants create noise.

Common Mistakes to Avoid

• Forgetting end keywords. Every alt, loop, opt, or par block must be closed with end. Missing end is the most common Mermaid syntax error and produces confusing render failures.
• Mixing arrow types incorrectly. ->> and -->> are the correct operators. Typing a single dash or using ==>> will cause a parse error.
• Omitting the colon before labels. Every message arrow must include a colon and label: A->>B: Label. Without the colon, Mermaid cannot parse the line.
• Using reserved words as aliases. Words like end, loop, and alt are reserved. If you need a participant named "End User", use participant EU as End User.

Related Resources

• Mermaid Plus for Confluence usage guide — detailed configuration options, theme settings, and all 26 supported diagram types
• Mermaid Syntax Cheat Sheet — quick reference for all Mermaid diagram types supported in Confluence
• Mermaid Troubleshooting FAQ — solutions for common rendering issues, syntax errors, and export problems
• Create Mermaid diagrams in Confluence — broader guide covering flowcharts, class diagrams, Gantt charts, and more
• Confluence diagram tools compared — side-by-side comparison of Mermaid, PlantUML, Draw.io, and Lucidchart for Confluence

Sequence diagrams are a high-leverage investment in your team's documentation. A well-written Mermaid sequence diagram takes minutes to create, lives alongside your other Confluence content, and stays up to date with a simple text edit. Install Mermaid Plus for Confluence, paste one of the examples above into a page, and start documenting your system interactions today.