Mermaid Sequence Diagrams in Confluence: FAQ & Examples

Sequence diagrams are one of the most widely used diagram types in software documentation. They show exactly how participants -- users, services, databases, external APIs -- exchange messages over time. For Confluence teams, embedding sequence diagrams directly on wiki pages means architecture docs, API specifications, and incident post-mortems stay in one place instead of scattered across external tools.

Mermaid's text-based syntax makes sequence diagrams fast to write and easy to update, but the syntax has its own set of rules that can trip you up. This FAQ answers the questions Confluence users ask most often about building sequence diagrams with Mermaid, with expanded explanations, working code examples, and copy-paste templates you can drop straight into a Mermaid Plus macro.

How do I create a sequence diagram in Confluence with Mermaid?

Creating a sequence diagram in Confluence requires two things: a Mermaid-compatible macro on the page and the correct sequenceDiagram syntax in the macro body. Here is the step-by-step process.

Step 1: Install Mermaid Plus for Confluence. Go to the Atlassian Marketplace, search for Mermaid Plus for Confluence, and click Get App. If your organization requires admin approval for marketplace apps, submit a request through your internal process. Once installed, the macro is available in every Confluence space.

Step 2: Insert the macro on a page. 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 opens where you can write and preview your diagram.

Step 3: Write the sequence diagram code. Start with the sequenceDiagram keyword, declare your participants, and add messages between them:

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant DB as Database

    Client->>API: POST /users
    API->>DB: INSERT INTO users
    DB-->>API: Row created
    API-->>Client: 201 Created

Step 4: Preview and publish. Click Preview inside the macro editor to verify the diagram renders correctly. When you are satisfied, click Save on the macro, then Publish the Confluence page.

The participant keyword is optional -- Mermaid will infer participants from the message lines -- but declaring them explicitly gives you control over the display order and lets you use the as keyword to set friendly display names while keeping short aliases in the code.

What arrow types does Mermaid support in sequence diagrams?

Arrow types are the most important visual cue in a sequence diagram. Different arrow styles communicate different types of interactions, and using them consistently makes your diagrams immediately understandable.

Mermaid supports six distinct arrow operators for sequence diagrams:

Arrow Type	Syntax	Meaning	When to Use
Solid arrow with message	A->>B: Text	Synchronous request	Direct calls, RPCs, form submissions
Dashed arrow with message	A-->>B: Text	Response or return	Return values, acknowledgments
Solid open arrow	A-)B: Text	Asynchronous message	Event emissions, fire-and-forget calls
Dashed open arrow	A--)B: Text	Asynchronous return	Callback completions
Solid line (no arrowhead)	A-B: Text	Flat connection	General association
Dashed line (no arrowhead)	A--B: Text	Dashed flat connection	Weak or indirect association

Here is an example that uses both solid and dashed arrows to distinguish between requests and responses:

sequenceDiagram
    participant User
    participant Web as Web App
    participant Auth as Auth Service
    participant DB as User Store

    User->>Web: Login with credentials
    Web->>Auth: Validate credentials
    Auth->>DB: Lookup user record
    DB-->>Auth: User data
    Auth-->>Web: JWT token
    Web-->>User: Dashboard loaded

A common convention is to use ->> for all outgoing requests and -->> for all responses. This creates a clear visual rhythm where solid lines go left-to-right (or top-to-bottom) and dashed lines come back. Your team should agree on a convention and apply it consistently across all sequence diagrams in your documentation.

How do I add conditional logic (if/else) in Mermaid sequence diagrams?

Real-world interactions are rarely linear. Conditional branches -- where the flow diverges based on a condition -- are modeled in Mermaid using alt/else/end blocks. Every alt block must be closed with an end keyword, and you can include one or more else sections for alternative paths.

Here is a basic alt/else block:

sequenceDiagram
    participant User
    participant API as Payment API
    participant Bank as Bank Gateway

    User->>API: Process payment
    API->>Bank: Charge card

    alt Charge succeeds
        Bank-->>API: 200 OK, charge_id
        API-->>User: Payment confirmed
    else Charge declined
        Bank-->>API: 402 Declined
        API-->>User: Payment failed
    end

You can also nest alt blocks for multi-level conditional logic. For example, a payment flow might first check whether the card is valid, then check whether sufficient funds are available:

sequenceDiagram
    participant User
    participant API as Payment API
    participant Bank as Bank Gateway

    User->>API: Process payment
    API->>Bank: Validate and charge

    alt Card is valid
        Bank->>Bank: Check balance
        alt Sufficient funds
            Bank-->>API: Charge successful
            API-->>User: Payment confirmed
        else Insufficient funds
            Bank-->>API: Insufficient funds
            API-->>User: Payment declined - low balance
        end
    else Card declined
        Bank-->>API: Card rejected
        API-->>User: Invalid card details
    end

For optional steps that have no alternative -- meaning they may or may not happen -- use the opt block instead of alt:

sequenceDiagram
    participant Client
    participant API as API

    Client->>API: Place order
    API-->>Client: Order confirmed

    opt User is premium member
        API->>API: Apply discount
        API-->>Client: Discount applied
    end

A few things to watch for when working with conditional blocks:

• Every alt must have exactly one matching end. Count them carefully before publishing.
• You cannot use else outside of an alt block.
• opt blocks do not take an else clause because they represent an optional step, not a branching choice.

Can I add loops in Mermaid sequence diagrams?

Yes. Loops are one of the most useful constructs in sequence diagrams because they let you model retry logic, polling intervals, batch processing, and any other repeated interaction. Mermaid uses the loop keyword followed by a description and closed with end.

Here is a basic loop that models a client polling a server for job status:

sequenceDiagram
    participant Client
    participant Server as Job Server

    Client->>Server: Submit job
    Server-->>Client: Job ID: 12345

    loop Poll every 5 seconds
        Client->>Server: GET /jobs/12345
        Server-->>Client: Status: processing
    end

    Client->>Server: GET /jobs/12345
    Server-->>Client: Status: complete

The rendered diagram draws a labeled rectangle around the messages inside the loop block, making it visually distinct from the surrounding flow. The description text appears as a label in the top-left corner of the rectangle.

Loops are frequently combined with alt blocks to model retry-with-fallback patterns:

sequenceDiagram
    participant Client
    participant Service as Downstream Service

    Client->>Service: Send request

    alt Service responds
        Service-->>Client: 200 OK
    else Service times out
        loop Retry up to 3 times
            Client->>Service: Retry request
            alt Success on retry
                Service-->>Client: 200 OK
            else Still failing
                Note right of Client: Wait 2s, then retry
            end
        end
    end

You can nest loops inside alt blocks and vice versa, but be careful with deeply nested structures. Each nesting level adds complexity and makes the diagram harder to read. If you find yourself going three or more levels deep, consider splitting the diagram into two separate diagrams and linking them with descriptive text.

How do I add notes to a Mermaid sequence diagram?

Notes let you annotate specific participants or spans of the diagram with contextual information that does not belong in the message flow itself. Mermaid supports three note placement options:

• Note left of A: Text -- places a note to the left of participant A
• Note right of A: Text -- places a note to the right of participant A
• Note over A,B: Text -- places a note spanning from participant A to participant B

Here is an example that uses all three:

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant DB as Database

    Note left of Client: Mobile app user
    Client->>API: GET /products
    Note over Client,API: TLS 1.3 encrypted
    API->>DB: SELECT * FROM products
    DB-->>API: Result set
    API-->>Client: JSON response
    Note right of DB: Read replica

Notes are best used for annotations that help a reader understand the diagram without cluttering the message arrows. Good candidates for notes include:

• Security annotations (encrypted connections, authentication method)
• Infrastructure context (read replica, cache layer, load balancer)
• Business rules that apply to a specific step
• SLA or performance targets for a particular call
• References to external documentation or runbooks

Avoid using notes for information that belongs in the message labels themselves. If you find yourself writing a note that says "Client sends a login request," put that information in the arrow label instead: Client->>API: POST /auth/login. Notes should add information that is not already conveyed by the message flow.

For multiline notes, Mermaid does not support explicit line breaks within a single Note statement in all versions. If you need a longer annotation, consider placing it in the surrounding Confluence text rather than inside the diagram.

Why is my sequence diagram not rendering in Confluence?

When a sequence diagram shows raw code instead of a rendered diagram, or when it renders partially and then stops, the cause is almost always a syntax error. Here are the most common issues and how to fix each one.

Missing sequenceDiagram keyword. Every Mermaid sequence diagram must begin with the sequenceDiagram keyword on its own line. Without it, Mermaid does not know what type of diagram to render.

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello

Unclosed alt or loop blocks. Every alt, opt, loop, par, and critical block must have a matching end. If you open three blocks, you need three end statements. Missing end keywords are the single most common cause of failed renders.

%% INCORRECT -- missing end
alt Condition A
    A->>B: Action
else Condition B
    A->>B: Other action
%% No end keyword!

%% CORRECT
alt Condition A
    A->>B: Action
else Condition B
    A->>B: Other action
end

Special characters in labels not wrapped in quotes. If a message label contains parentheses, brackets, or other special characters, wrap the label in double quotes:

%% INCORRECT
A->>B: Send (urgent) message

%% CORRECT
A->>B: "Send (urgent) message"

Missing colon before message text. Every arrow must include a colon followed by the message text. Without the colon, Mermaid cannot parse the line:

%% INCORRECT
A->>B Send data

%% CORRECT
A->>B: Send data

The Mermaid macro is not installed or enabled. If typing /mermaid in the Confluence editor does not show a macro option, the Mermaid Plus app may not be installed. Check Confluence Administration > Apps to verify the app is present and active.

The fastest way to debug. Copy your Mermaid code and paste it into the Mermaid Live Editor. The Live Editor renders the diagram in real time and highlights the exact line where parsing fails. Fix the error in the Live Editor, then paste the corrected code back into Confluence.

Sequence Diagram Syntax Quick Reference

Keep this table handy when writing sequence diagrams in Confluence. It covers every commonly used syntax element.

Element	Syntax	Description
Diagram type	sequenceDiagram	Required first line
Participant	participant A as Alice	Declare a named participant with alias
Actor	actor User	Stick-figure actor instead of box
Solid message	A->>B: Text	Synchronous request or call
Dashed message	A-->>B: Text	Response, return value, async reply
Open arrow (solid)	A-)B: Text	Asynchronous message
Open arrow (dashed)	A--)B: Text	Asynchronous return
Note (left)	Note left of A: Text	Note to the left of a participant
Note (right)	Note right of A: Text	Note to the right of a participant
Note (spanning)	Note over A,B: Text	Note spanning multiple participants
Conditional	alt Cond ... else ... end	If/else branching
Optional	opt Cond ... end	Optional step, no else
Loop	loop Desc ... end	Repeated interaction
Parallel	par ... and ... end	Concurrent execution
Critical	critical ... option ... end	Must-complete block with fallback
Activate bar	activate A	Show active processing on participant
Deactivate bar	deactivate A	Remove activation bar
Shortcut activation	A->>+B: Text	Activate B automatically
Shortcut deactivation	A->>-B: Text	Deactivate B automatically
Auto-numbering	autonumber	Number messages sequentially
Comment	%% Text	Inline comment, not rendered
Delay	...	Visual delay/spacer in the timeline
Background	rect rgb(r,g,b) ... end	Colored background for a section

Copy-Paste Sequence Diagram Examples

The following three examples are complete, ready to paste into a Mermaid Plus macro in Confluence. Modify the participants, messages, and labels to match your own architecture.

Example 1: Authentication Flow with Token Refresh

This diagram shows a full OAuth 2.0-style authentication flow including login, token issuance, resource access, and token refresh. It covers the happy path and the expired-token recovery path.

sequenceDiagram
    autonumber
    actor User
    participant FE as Frontend
    participant Auth as Auth Service
    participant Resource as Resource Server
    participant Cache as Token Store

    User->>FE: Enter email and password
    FE->>Auth: POST /auth/login {email, password}
    Auth->>Auth: Validate credentials

    alt Valid credentials
        Auth->>Cache: Store refresh token
        Auth-->>FE: 200 {access_token, refresh_token, expires_in}
        FE->>FE: Store tokens in memory
        FE-->>User: Redirect to dashboard

        Note over User,Resource: --- Subsequent API calls ---

        User->>FE: View profile
        FE->>Resource: GET /api/profile (Authorization: Bearer <token>)
        Resource->>Auth: Validate access token
        Auth-->>Resource: Token valid
        Resource-->>FE: 200 {user profile}
        FE-->>User: Display profile

        Note over User,Auth: --- Token expires after 1 hour ---

        User->>FE: View orders
        FE->>Resource: GET /api/orders (Authorization: Bearer <expired>)
        Resource-->>FE: 401 Token expired
        FE->>Auth: POST /auth/refresh {refresh_token}
        Auth->>Cache: Verify refresh token
        Cache-->>Auth: Token valid
        Auth-->>FE: 200 {new_access_token}
        FE->>Resource: GET /api/orders (Authorization: Bearer <new>)
        Resource-->>FE: 200 {orders}
        FE-->>User: Display orders
    else Invalid credentials
        Auth-->>FE: 401 Unauthorized
        FE-->>User: Show error: Invalid email or password
    end

Example 2: Order Processing with Inventory and Payment

This diagram models an e-commerce order placement flow. It shows the synchronous calls to inventory and payment services, the event-driven notification, and the rollback path when payment fails.

sequenceDiagram
    autonumber
    participant Customer
    participant Web as Web App
    participant Order as Order Service
    participant Inv as Inventory Service
    participant Pay as Payment Service
    participant Bus as Event Bus
    participant Email as Email Service

    Customer->>Web: Place order
    Web->>Order: POST /orders {items, payment_method}
    activate Order

    Order->>Inv: POST /inventory/reserve {items}
    activate Inv

    alt Items in stock
        Inv-->>Order: 200 {reservation_id}
        deactivate Inv

        Order->>Pay: POST /payments/charge {amount, method}
        activate Pay

        alt Payment succeeds
            Pay-->>Order: 200 {charge_id}
            deactivate Pay
            Order->>Order: Create order record
            Order->>Bus: Publish order.created event
            Bus-->>Email: Deliver event
            Email->>Email: Send confirmation email
            Order-->>Web: 201 {order_id, status: confirmed}
            Web-->>Customer: Order confirmation page
        else Payment fails
            Pay-->>Order: 402 Payment declined
            deactivate Pay
            Order->>Inv: POST /inventory/release {reservation_id}
            Inv-->>Order: 200 Released
            Order-->>Web: 402 {error: payment_declined}
            Web-->>Customer: Payment failed, try again
        end
    else Items out of stock
        Inv-->>Order: 409 {error: insufficient_stock}
        deactivate Inv
        Order-->>Web: 409 Out of stock
        Web-->>Customer: Items unavailable
    end

    deactivate Order

Example 3: Error Handling with Retry and Circuit Breaker

This diagram illustrates a resilient client calling a downstream service through retry middleware and a circuit breaker. It covers the healthy path, the retry path, and the circuit-open fallback.

sequenceDiagram
    autonumber
    participant App as Application
    participant Retry as Retry Middleware
    participant CB as Circuit Breaker
    participant Svc as Downstream Service
    participant Fallback as Fallback Service

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

    alt Circuit is closed (healthy)
        CB->>Svc: Proxy request
        alt Service responds successfully
            Svc-->>CB: 200 OK
            CB->>CB: Record success
            CB-->>Retry: 200 OK
            Retry-->>App: Success response
        else Service returns 5xx
            Svc-->>CB: 503 Unavailable
            CB->>CB: Record failure

            loop Retry up to 3 times with exponential backoff
                Retry->>CB: Retry request
                CB->>Svc: Proxy request
                alt Retry succeeds
                    Svc-->>CB: 200 OK
                    CB-->>Retry: 200 OK
                else Retry fails
                    Svc-->>CB: 503 Unavailable
                    CB->>CB: Increment failure count
                end
            end

            alt At least one retry succeeded
                CB-->>Retry: 200 OK
                Retry-->>App: Success response
            else All retries exhausted
                CB->>CB: Open circuit
                CB->>Fallback: Request fallback response
                Fallback-->>CB: Cached or default data
                CB-->>Retry: Degraded response
                Retry-->>App: 200 with fallback data
                Note right of CB: Circuit stays open for 30s
            end
        end
    else Circuit is open (tripped)
        CB->>Fallback: Serve from cache
        Fallback-->>CB: Stale data
        CB-->>Retry: Degraded response
        Retry-->>App: 200 with cached data
        Note over CB: After 30s timeout, circuit goes to half-open
    end

Tips for Readable Sequence Diagrams

A sequence diagram is only useful if your team can read and understand it at a glance. These tips help you produce diagrams that communicate clearly.

Limit participants to five or six. Each additional participant reduces the horizontal space available for message labels. If your architecture involves more than six actors, split the interaction into multiple diagrams. For example, diagram the client-to-gateway interaction separately from the gateway-to-backend interaction.

Use the as keyword for short aliases. Write participant AuthSvc as Authentication Service in your code. This keeps the Mermaid source readable while displaying the full name in the rendered diagram. Short aliases also reduce the chance of typos when writing arrow statements.

Auto-number your messages. Add autonumber on the line immediately after sequenceDiagram. Numbered messages give your team a shared vocabulary for discussing specific steps ("the issue is at step 4 where the API gateway times out").

Be consistent with arrow conventions. Agree with your team that solid arrows (->>) always represent requests and dashed arrows (-->>) always represent responses. Consistent visual language reduces the cognitive load of reading the diagram.

Add notes for non-obvious context. Use Note over A,B: Text for cross-cutting concerns like encryption, rate limiting, or SLA boundaries. Place notes only where they add information that is not already in the message labels.

Split large diagrams by phase. If a single diagram would exceed 20 to 25 messages, break it into phases. For example, split an order flow into "Order Placement," "Payment Processing," and "Fulfillment" diagrams. Link them with a brief prose description on the Confluence page.

Use activate and deactivate sparingly. Activation bars show when a participant is actively processing a request. They add visual clarity to simple diagrams but create clutter in complex ones. Use them for the most important service interactions and omit them for trivial pass-through calls.

Test in the Mermaid Live Editor first. Before pasting code into Confluence, validate it at mermaid.live. The Live Editor shows rendering errors in real time, which is faster than saving, publishing, and reloading a Confluence page to check each change.

Related Resources

• Mermaid Plus for Confluence -- complete usage guide with configuration, themes, and all 26 supported diagram types
• How to Create Sequence Diagrams in Confluence -- step-by-step tutorial for building sequence diagrams from scratch
• Mermaid Syntax Cheat Sheet -- quick reference for all Mermaid diagram types supported in Confluence
• Mermaid Troubleshooting FAQ -- solutions for rendering issues, syntax errors, and performance problems
• Create Mermaid Diagrams in Confluence -- broader guide covering flowcharts, class diagrams, Gantt charts, and more