# Documenting Microservice Architectures in Confluence with Mermaid — Syntax Patterns That Scale

May 2, 2026 ·

<!-- -->

14 min read

[NGPilot](https://ngpilot.com)

Mermaid is the most popular text-based diagramming language for technical documentation. One line of code generates a flowchart. A few more produce a sequence diagram, ER diagram, or Gantt chart. Teams using Confluence can embed Mermaid diagrams directly on their pages, keeping diagrams alongside the documentation they illustrate.

Who should read this

* **Platform/backend engineers** documenting a microservice architecture
* **Tech leads** keeping architecture docs in sync with code
* **Anyone** who wants a copy-paste Mermaid syntax reference for Confluence

The scenario we'll work through is the one most engineering teams hit: you run a handful of microservices, requests bounce between them, and onboarding a new engineer means drawing the system on a whiteboard every time. The fix is to capture that architecture once, in text, inside Confluence — so it versions with your docs and survives a whiteboard being wiped. Below are the four diagram patterns that cover most of a microservice architecture, each with copy-paste syntax. The full node-shape and arrow reference follows, so the same page works as both a worked example and a syntax cheat sheet.

## The four diagrams that document a microservice architecture[​](#the-four-diagrams-that-document-a-microservice-architecture "Direct link to The four diagrams that document a microservice architecture")

### 1. The service map (flowchart with subgraphs)[​](#1-the-service-map-flowchart-with-subgraphs "Direct link to 1. The service map (flowchart with subgraphs)")

Start with a high-level map showing every service and how requests enter the system. Use `subgraph` to group services by boundary (edge, core, data) so the diagram reads in layers rather than as a hairball.

To render Mermaid diagrams on your Confluence pages, you need a Mermaid macro. Here are three options, ranked by features:

1. **[Mermaid Plus for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md)** — dedicated Mermaid editor with 29 diagram types, live preview, templates, and customizable themes. Type `/mermaid` to insert the macro. Install from the [Atlassian Marketplace](https://marketplace.atlassian.com/).

2. **[Diagram Duo for Confluence](/docs/diagram-duo-for-confluence/usage.md)** — combines a full Mermaid editor **and** an Excalidraw visual canvas in one macro. Best choice if your team uses both text-based and visual diagrams. Type `/mermaid` or `/excalidraw` on any page.

3. **Confluence built-in Mermaid macro** — limited to basic diagram types with no template library or theme customization.

All examples on this page work with any of these options. Copy the code, paste it into the macro, and publish.

## Quick Syntax Reference[​](#quick-syntax-reference "Direct link to Quick Syntax Reference")

***

## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions")

### 1. How do I create a flowchart in Mermaid?[​](#1-how-do-i-create-a-flowchart-in-mermaid "Direct link to 1. How do I create a flowchart in Mermaid?")

Flowcharts are the most popular Mermaid diagram type. Start with the `flowchart` keyword followed by a direction indicator:

* `TD` or `TB` -- top-down (top to bottom)
* `BT` -- bottom to top
* `LR` -- left to right
* `RL` -- right to left

Then define nodes and connections:

```
flowchart TD

  A[Start] --> B{Decision}

  B -->|Yes| C[Process Action]

  B -->|No| D[End]

  C --> D
```

The direction keyword controls the overall layout. Every node is referenced by an ID (like `A`, `B`, `C`) and you define its shape with brackets around the label text.

### 2. How do I add text labels to Mermaid arrows?[​](#2-how-do-i-add-text-labels-to-mermaid-arrows "Direct link to 2. How do I add text labels to Mermaid arrows?")

Labels on arrows make your diagrams self-documenting. Use the pipe `|` character immediately after the arrow operator:

```
flowchart LR

  A[Submit Request] -->|Approved| B[Process Payment]

  A -->|Rejected| C[Notify Customer]
```

For longer labels that contain special characters, wrap the label text in double quotes:

```
flowchart LR

  A -->|"Long label with (special) characters"| B
```

You can also place labels on the arrow using the `-- text -->` syntax:

```
flowchart LR

  A -- Review needed --> B
```

### 3. How do I create subgraphs in Mermaid?[​](#3-how-do-i-create-subgraphs-in-mermaid "Direct link to 3. How do I create subgraphs in Mermaid?")

Subgraphs group related nodes together visually with a bordered box. Use the `subgraph` keyword, indent the grouped content, and close with `end`:

```
flowchart TB

  subgraph Frontend

    A[UI Layer] --> B[State Management]

  end

  subgraph Backend

    C[API Gateway] --> D[Service Layer]

  end

  B --> C
```

You can also give a subgraph a display title and control its direction independently:

```
flowchart TB

  subgraph Auth["Authentication Module"]

    direction LR

    E[Login] --> F[Token Validation]

    F --> G[Session]

  end
```

### 4. How do I style nodes with different shapes?[​](#4-how-do-i-style-nodes-with-different-shapes "Direct link to 4. How do I style nodes with different shapes?")

Mermaid uses different bracket types to control node shapes. Here is a comprehensive reference:

```
flowchart LR

  A[Rounded Rectangle]

  B([Stadium / Pill Shape])

  C[[Subroutine]]

  D[(Database Cylinder)]

  E((Circle))

  F>Asymmetric Flag]

  G{Diamond / Decision}

  H{{Hexagon}}
```

| Bracket Syntax | Shape             | Typical Use            |
| -------------- | ----------------- | ---------------------- |
| `[text]`       | Rounded rectangle | Standard process step  |
| `([text])`     | Stadium / pill    | Start or end terminal  |
| `[[text]]`     | Subroutine        | Reusable process       |
| `[(text)]`     | Cylinder          | Database or data store |
| `((text))`     | Circle            | Junction or connector  |
| `>text]`       | Asymmetric        | Manual input or output |
| `{text}`       | Diamond           | Decision point         |
| `{{text}}`     | Hexagon           | Preparation step       |

### 5. What is the correct syntax for a sequence diagram?[​](#5-what-is-the-correct-syntax-for-a-sequence-diagram "Direct link to 5. What is the correct syntax for a sequence diagram?")

Sequence diagrams show interactions between participants over time. Start with the `sequenceDiagram` keyword:

```
sequenceDiagram

  participant User

  participant Frontend

  participant API

  participant DB



  User->>Frontend: Submit form

  Frontend->>API: POST /api/orders

  API->>DB: INSERT query

  DB-->>API: Confirmation

  API-->>Frontend: 201 Created

  Frontend-->>User: Success message
```

Key arrow types for sequence diagrams:

* `->>` solid line with arrowhead (synchronous request)
* `-->>` dashed line with arrowhead (response or return)
* `--)` solid line with open arrow (asynchronous message)
* `--)` dashed line with open arrow (asynchronous return)

Add notes to clarify specific steps:

```
sequenceDiagram

  participant A as Client

  participant B as Server

  Note over A: User initiates request

  A->>B: GET /data

  Note over A,B: TLS encrypted

  B-->>A: JSON response
```

### 6. How do I create an ER diagram in Mermaid?[​](#6-how-do-i-create-an-er-diagram-in-mermaid "Direct link to 6. How do I create an ER diagram in Mermaid?")

Entity-relationship diagrams use the `erDiagram` keyword. Define entities with their attributes and relationships between them:

```
erDiagram

  CUSTOMER ||--o{ ORDER : "places"

  ORDER ||--|{ LINE_ITEM : "contains"

  CUSTOMER {

    int id PK

    string name

    string email

    date created_at

  }

  ORDER {

    int id PK

    int customer_id FK

    date order_date

    string status

  }

  LINE_ITEM {

    int id PK

    int order_id FK

    string product_name

    int quantity

    float price

  }
```

Relationship notation uses these operators:

| Symbol       | Meaning             |
| ------------ | ------------------- |
| `\|\|`       | Exactly one         |
| `o{`         | Zero or more        |
| `\|\|--o{`   | One to zero-or-more |
| `\|\|--\|{`  | One to one-or-more  |
| `\|\|--\|\|` | One to one          |

### 7. How do I create a class diagram in Mermaid?[​](#7-how-do-i-create-a-class-diagram-in-mermaid "Direct link to 7. How do I create a class diagram in Mermaid?")

Class diagrams use the `classDiagram` keyword. Define classes with their attributes, methods, and relationships:

```
classDiagram

  class Animal {

    +String name

    +int age

    +makeSound() void

    +move() void

  }

  class Dog {

    +String breed

    +fetch() void

    +bark() void

  }

  class Cat {

    +bool indoor

    +purr() void

    +scratch() void

  }

  Animal <|-- Dog

  Animal <|-- Cat
```

Visibility modifiers:

* `+` public
* `-` private
* `#` protected

Relationship types include `<|--` (inheritance), `*--` (composition), `o--` (aggregation), `-->` (association), and `..>` (dependency).

### 8. How do I create a Gantt chart in Mermaid?[​](#8-how-do-i-create-a-gantt-chart-in-mermaid "Direct link to 8. How do I create a Gantt chart in Mermaid?")

Gantt charts visualize project schedules using the `gantt` keyword:

```
gantt

  title Project Timeline

  dateFormat YYYY-MM-DD

  axisFormat %b %d



  section Planning

    Requirements gathering  :done, req, 2026-05-01, 10d

    Architecture design     :active, arch, after req, 5d



  section Development

    Frontend implementation :dev-fe, after arch, 15d

    Backend API             :dev-be, after arch, 12d

    Integration testing     :test, after dev-fe, 7d



  section Deployment

    Staging release         :stage, after test, 3d

    Production release      :prod, after stage, 2d
```

Task states include `done`, `active`, and (default) future tasks. You can set task dependencies using `after` followed by the task ID.

### 9. How do I add comments in Mermaid syntax?[​](#9-how-do-i-add-comments-in-mermaid-syntax "Direct link to 9. How do I add comments in Mermaid syntax?")

Comments use the `%%` prefix and are ignored during rendering:

```
flowchart LR

  %% This is a comment and will not appear in the diagram

  A[Start] --> B[End]

  %% You can also comment out lines for debugging

  %% A --> C[Hidden node]
```

Comments are useful for leaving notes for collaborators or temporarily disabling parts of a diagram during editing.

### 10. How do I style Mermaid diagrams with custom colors?[​](#10-how-do-i-style-mermaid-diagrams-with-custom-colors "Direct link to 10. How do I style Mermaid diagrams with custom colors?")

Use the `style` keyword to apply CSS-like properties to specific nodes:

```
flowchart LR

  A[Start] --> B[Process] --> C[End]

  style A fill:#4CAF50,stroke:#2E7D32,color:#fff

  style B fill:#2196F3,stroke:#1565C0,color:#fff

  style C fill:#f44336,stroke:#c62828,color:#fff
```

For reusable styles, define class definitions with `classDef`:

```
flowchart LR

  A[Start] --> B[Process] --> C[End]

  classDef green fill:#e8f5e9,stroke:#4CAF50,stroke-width:2px

  classDef blue fill:#e3f2fd,stroke:#2196F3,stroke-width:2px

  class A green

  class B,C blue
```

### 11. How do I use Mermaid diagrams in Confluence?[​](#11-how-do-i-use-mermaid-diagrams-in-confluence "Direct link to 11. How do I use Mermaid diagrams in Confluence?")

You have three options for rendering Mermaid diagrams in Confluence:

**[Mermaid Plus for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md)** (recommended) — dedicated Mermaid editor with 29 diagram types, live preview, templates, and theme customization. Best if your team wants a focused Mermaid experience.

1. Install Mermaid Plus from the Atlassian Marketplace
2. Open a Confluence page in edit mode
3. Type `/mermaid` and select the Mermaid Plus macro
4. Paste your Mermaid code into the code editor
5. Preview, save, and publish the page

**[Diagram Duo for Confluence](/docs/diagram-duo-for-confluence/usage.md)** — combines a Mermaid code editor with an Excalidraw visual canvas in one macro. Switch between text-based and visual diagramming on the same page. Type `/mermaid` or `/excalidraw` to insert.

**Confluence built-in macro** — supports basic diagram types with no template library or theme options. Good for getting started quickly.

All three options render the Mermaid syntax documented in this cheat sheet.

### 12. How do I create a pie chart in Mermaid?[​](#12-how-do-i-create-a-pie-chart-in-mermaid "Direct link to 12. How do I create a pie chart in Mermaid?")

Pie charts use the `pie` keyword:

```
pie title Market Share by Region

  "North America" : 35

  "Europe" : 28

  "Asia Pacific" : 25

  "Latin America" : 8

  "Other" : 4
```

The values are treated as relative proportions. Mermaid calculates the percentages automatically based on the total.

### 13. How do I create a state diagram in Mermaid?[​](#13-how-do-i-create-a-state-diagram-in-mermaid "Direct link to 13. How do I create a state diagram in Mermaid?")

State diagrams use the `stateDiagram-v2` keyword (the v2 version supports more features):

```
stateDiagram-v2

  [*] --> Idle

  Idle --> Processing : Start

  Processing --> Success : Complete

  Processing --> Error : Failure

  Error --> Idle : Retry

  Success --> [*]
```

Use `[*]` to denote the start and end states. Add labels to transitions with a colon after the target state.

### 14. How do I create a mind map in Mermaid?[​](#14-how-do-i-create-a-mind-map-in-mermaid "Direct link to 14. How do I create a mind map in Mermaid?")

Mind maps are supported in Mermaid v9.3 and later using the `mindmap` keyword:

```
mindmap

  root((Central Topic))

    Branch A

      Sub-topic A1

      Sub-topic A2

    Branch B

      Sub-topic B1

        Detail B1a

        Detail B1b

      Sub-topic B2

    Branch C

      Sub-topic C1
```

Indentation defines the hierarchy. Each level of indentation creates a deeper branch.

### 15. How do I troubleshoot Mermaid diagrams that do not render?[​](#15-how-do-i-troubleshoot-mermaid-diagrams-that-do-not-render "Direct link to 15. How do I troubleshoot Mermaid diagrams that do not render?")

When a Mermaid diagram fails to render in Confluence, check these common issues:

* **Missing keyword**: Every diagram must start with a valid keyword (`flowchart`, `sequenceDiagram`, `erDiagram`, etc.)
* **Incorrect indentation**: Some diagram types are sensitive to indentation, especially subgraphs and class definitions
* **Special characters in labels**: Wrap labels containing special characters in double quotes
* **Trailing whitespace**: Extra spaces at the end of lines can sometimes cause parsing errors
* **Unsupported features**: Confluence may use an older version of Mermaid that does not support newer features like mind maps

For a comprehensive troubleshooting guide, see [Mermaid Not Rendering? Fixes and FAQ](/blog/faq-mermaid-troubleshooting.md).

***

## Quick Syntax Reference[​](#quick-syntax-reference-1 "Direct link to Quick Syntax Reference")

| Element            | Syntax                  | Example                        |
| ------------------ | ----------------------- | ------------------------------ |
| Flowchart          | `flowchart TD/LR`       | `flowchart TD`                 |
| Sequence diagram   | `sequenceDiagram`       | `sequenceDiagram`              |
| Class diagram      | `classDiagram`          | `classDiagram`                 |
| ER diagram         | `erDiagram`             | `erDiagram`                    |
| Gantt chart        | `gantt`                 | `gantt`                        |
| State diagram      | `stateDiagram-v2`       | `stateDiagram-v2`              |
| Pie chart          | `pie`                   | `pie title Sales`              |
| Mind map           | `mindmap`               | `mindmap`                      |
| Arrow with label   | \`-->                   | text                           |
| Dashed arrow       | `-.->`                  | `A -.-> B`                     |
| Thick arrow        | `==>`                   | `A ==> B`                      |
| Subgraph           | `subgraph Name ... end` | `subgraph Auth\n A --> B\nend` |
| Comment            | `%% text`               | `%% This is a comment`         |
| Node style         | `style ID fill:#hex`    | `style A fill:#4CAF50`         |
| Rounded rectangle  | `A[text]`               | `A[Start]`                     |
| Diamond / decision | `A{text}`               | `B{Choice?}`                   |
| Circle             | `A((text))`             | `C((Merge))`                   |
| Database cylinder  | `A[(text)]`             | `DB[(Database)]`               |

***

## Frequently Asked Questions[​](#frequently-asked-questions-1 "Direct link to Frequently Asked Questions")

***

## 5 Copy-Paste Mermaid Diagrams[​](#5-copy-paste-mermaid-diagrams "Direct link to 5 Copy-Paste Mermaid Diagrams")

These five diagrams cover the most common patterns teams need. Copy any of them into your Confluence Mermaid macro and customize the content.

### Flowchart: User Registration Process[​](#flowchart-user-registration-process "Direct link to Flowchart: User Registration Process")

```
flowchart TD

  A([User visits signup page]) --> B[Fill registration form]

  B --> C{Valid input?}

  C -->|Yes| D[Create account]

  C -->|No| E[Show validation errors]

  E --> B

  D --> F{Email verification?}

  F -->|Verified| G[Activate account]

  F -->|Pending| H[Send reminder email]

  H --> I{Max retries?}

  I -->|No| H

  I -->|Yes| J[Deactivate account]

  G --> K([User logged in])
```

### Sequence Diagram: API Authentication Flow[​](#sequence-diagram-api-authentication-flow "Direct link to Sequence Diagram: API Authentication Flow")

```
sequenceDiagram

  participant Client

  participant AuthServer as Auth Server

  participant ResourceServer as Resource Server

  participant Cache as Redis Cache



  Client->>AuthServer: POST /oauth/token (credentials)

  AuthServer->>Cache: Check existing session

  Cache-->>AuthServer: No active session

  AuthServer->>AuthServer: Validate credentials

  AuthServer-->>Client: Access token + Refresh token

  Note over Client: Store tokens securely



  Client->>ResourceServer: GET /api/data (Bearer token)

  ResourceServer->>AuthServer: Validate token

  AuthServer-->>ResourceServer: Token valid

  ResourceServer-->>Client: 200 OK + JSON data



  Note over Client,AuthServer: After token expires

  Client->>AuthServer: POST /oauth/token (refresh token)

  AuthServer-->>Client: New access token
```

### Class Diagram: E-Commerce Order System[​](#class-diagram-e-commerce-order-system "Direct link to Class Diagram: E-Commerce Order System")

```
classDiagram

  class User {

    +int id

    +String name

    +String email

    +login() bool

    +logout() void

  }



  class Order {

    +int id

    +Date createdAt

    +String status

    +calculateTotal() float

    +cancel() bool

  }



  class Product {

    +int id

    +String name

    +float price

    +int stock

    +reduceStock(qty: int) void

  }



  class Payment {

    +int id

    +float amount

    +String method

    +process() bool

    +refund() bool

  }



  class OrderItem {

    +int quantity

    +float unitPrice

    +getSubtotal() float

  }



  User "1" --> "*" Order : places

  Order "1" --> "*" OrderItem : contains

  OrderItem "*" --> "1" Product : references

  Order "1" --> "1" Payment : paid by
```

### ER Diagram: Blog Platform Schema[​](#er-diagram-blog-platform-schema "Direct link to ER Diagram: Blog Platform Schema")

```
erDiagram

  AUTHOR ||--o{ POST : "writes"

  POST ||--o{ COMMENT : "receives"

  POST }o--|| CATEGORY : "belongs to"

  POST ||--o{ TAG_POST : "tagged with"

  TAG ||--o{ TAG_POST : "applied to"



  AUTHOR {

    int id PK

    string username

    string email

    string bio

    date joined_at

  }



  POST {

    int id PK

    int author_id FK

    int category_id FK

    string title

    text content

    string status

    date published_at

  }



  COMMENT {

    int id PK

    int post_id FK

    string author_name

    text body

    date created_at

  }



  CATEGORY {

    int id PK

    string name

    string slug

  }



  TAG {

    int id PK

    string name

    string slug

  }



  TAG_POST {

    int tag_id FK

    int post_id FK

  }
```

### Gantt Chart: Software Release Timeline[​](#gantt-chart-software-release-timeline "Direct link to Gantt Chart: Software Release Timeline")

```
gantt

  title Software Release v2.0 Timeline

  dateFormat YYYY-MM-DD

  axisFormat %b %d



  section Design

    UX research           :done, ux, 2026-04-01, 7d

    Wireframes            :done, wire, after ux, 5d

    Visual design         :done, vis, after wire, 7d



  section Development

    Frontend sprint 1     :active, fe1, 2026-04-21, 10d

    Frontend sprint 2     :fe2, after fe1, 10d

    Backend API           :be, 2026-04-21, 14d

    Integration           :int, after fe2, 5d



  section Testing

    QA regression         :qa, after int, 7d

    UAT                   :uat, after qa, 5d

    Bug fixes             :fix, after uat, 5d



  section Release

    Staging deploy        :stage, after fix, 2d

    Production deploy     :prod, after stage, 1d

    Post-release monitor  :mon, after prod, 5d
```

***

## Tips for Using Mermaid in Confluence[​](#tips-for-using-mermaid-in-confluence "Direct link to Tips for Using Mermaid in Confluence")

**Keep diagrams focused.** A single diagram should tell one story. If your flowchart has more than 15 nodes, consider splitting it into multiple diagrams with linking subgraphs.

**Use consistent naming.** Adopt a naming convention for your node IDs (like `step1`, `step2` or `A`, `B`, `C`) and stick with it across your team's diagrams. This makes collaboration and code reviews much easier.

**Test incrementally.** When building complex diagrams, add a few nodes at a time and preview after each addition. This makes it much easier to spot the exact change that broke the rendering.

**Leverage templates.** If your team creates similar diagrams repeatedly (onboarding flows, deployment pipelines, API interactions), save the Mermaid code as a Confluence template so everyone starts from a consistent baseline.

**Version your diagrams.** Since Mermaid is text-based, Confluence's page history captures every change. Use meaningful commit messages when updating complex diagrams so your team can track what changed and why.

***

## Related Resources[​](#related-resources "Direct link to Related Resources")

* [Mermaid Plus for Confluence](/apps/mermaid-plus-for-confluence.md) -- dedicated Mermaid editor with 29 diagram types, templates, and theme settings
* [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- visual drawing with 220+ shape libraries for architecture and design diagrams
* [Diagram Duo for Confluence](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- combined Mermaid + Excalidraw editor in one macro
* [Graphviz Charts for Confluence](/apps/graphviz-charts-for-confluence.md) -- alternative text-based diagramming with DOT/Graphviz syntax for network and graph diagrams
* [Confluence Diagram Tools Compared](/blog/confluence-diagram-tools-comparison.md) -- side-by-side comparison of diagramming options available for Confluence teams
* [Mermaid Diagram Types for Confluence](/blog/faq-mermaid-diagram-types-confluence.md) -- when to use each of the 29 diagram types
* [How to Create Gantt Charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) -- step-by-step guide with copy-paste examples
* [How to Create Pie Charts in Confluence](/blog/how-to-create-pie-charts-confluence.md) -- data visualization guide with Mermaid syntax
* [Free Confluence Diagram Plugin](/blog/confluence-free-diagram-plugin.md) -- free diagram apps compared

Try <!-- -->Mermaid Plus for Confluence

All 26 Mermaid diagram types with live preview and one-click templates — free for up to 10 users.

[Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence)

## 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:**

* [faq](/blog/tags/faq.md)
* [mermaid](/blog/tags/mermaid.md)
* [confluence](/blog/tags/confluence.md)
* [syntax](/blog/tags/syntax.md)
* [cheat-sheet](/blog/tags/cheat-sheet.md)
* [diagrams](/blog/tags/diagrams.md)