# How to Create Sequence Diagrams in Confluence (Mermaid Examples) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) 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?[​](#why-sequence-diagrams-in-confluence "Direct link to 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[​](#step-by-step-create-your-first-sequence-diagram "Direct link to 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[​](#step-1--install-mermaid-plus-for-confluence "Direct link to Step 1 — Install Mermaid Plus for Confluence") Head to the [Atlassian Marketplace](https://marketplace.atlassian.com/) 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[​](#step-2--insert-the-mermaid-macro "Direct link to 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[​](#step-3--write-the-sequencediagram-header "Direct link to 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[​](#step-4--add-message-arrows "Direct link to 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[​](#step-5--save-and-publish "Direct link to 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[​](#mermaid-sequence-diagram-syntax-reference "Direct link to 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[​](#5-copy-paste-sequence-diagram-examples "Direct link to 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[​](#example-1--user-login-flow "Direct link to 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[​](#example-2--api-requestresponse "Direct link to 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[​](#example-3--microservice-communication "Direct link to 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[​](#example-4--database-transaction "Direct link to 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[​](#example-5--error-handling-flow "Direct link to 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[​](#tips-for-complex-sequence-diagrams "Direct link to 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[​](#use-alt-and-else-blocks-for-conditional-logic "Direct link to 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[​](#add-loops-for-retry-logic-and-polling "Direct link to 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[​](#annotate-with-notes-sparingly "Direct link to 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[​](#auto-number-messages "Direct link to 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[​](#keep-participant-names-short "Direct link to 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[​](#break-large-diagrams-into-smaller-ones "Direct link to 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[​](#use-styling-for-emphasis "Direct link to 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[​](#common-mistakes-to-avoid "Direct link to 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[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) — detailed configuration options, theme settings, and all 29 supported diagram types * [Mermaid Syntax Cheat Sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) — quick reference for all Mermaid diagram types supported in Confluence * [Mermaid Troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) — solutions for common rendering issues, syntax errors, and export problems * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — broader guide covering flowcharts, class diagrams, Gantt charts, and more * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) — 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. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md)