# Document Your Codebase in Confluence with Mermaid Class Diagrams

September 24, 2026 ·

<!-- -->

6 min read

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

Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where `PaymentService` does everything except the thing the diagram says `OrderService` does. Day-1 onboarding just taught two people the wrong architecture.

**Quick answer:** keep the architecture in Confluence as a Mermaid `class diagram`, rendered by [Mermaid Plus for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence/) and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch.

## Why the class diagram, not the screenshot[​](#why-the-class-diagram-not-the-screenshot "Direct link to Why the class diagram, not the screenshot")

A screenshot is a moment; a Mermaid class diagram is a *living boundary map*. The readers you care about ask three questions that a screenshot answers badly:

* **What do I call?** The public classes at each module's edge
* **What implements it?** Where the interface points are, and who swaps in
* **What breaks?** What an internal change leaks out of the module

A class diagram answers these in visible text — and because it is Mermaid, the answer stays honest: move a class, and the diagram moves in the same edit. New hires learn the *current* shape by default, not the whiteboard from last year.

## Copy-paste 1: the onboarding service map[​](#copy-paste-1-the-onboarding-service-map "Direct link to Copy-paste 1: the onboarding service map")

Start with the map a new hire wants: the services, their public side, and which service owns which data. Six classes, one owner per class, arrows only where code actually calls:

```
classDiagram

  %% title: Service ownership map — order flow

  class OrderService {

    +placeOrder(dto) Order

    +cancelOrder(id) void

    -orderRepo OrderRepository

  }

  class PaymentService {

    +charge(order) Receipt

    -paymentRepo

  }

  class InventoryService {

    +reserve(items) bool

    -stockRepo

  }

  class NotificationService {

    +send(event) void

  }

  OrderService --> PaymentService : charges

  OrderService --> InventoryService : reserves

  PaymentService --> NotificationService : emits ReceiptConfirmed
```

![Service ownership map — order flow](/assets/images/service-ownership-map-order-flow-7592f0cabccdeafeef48da8eec4ea939.svg)

Three relations carry the architecture: order charges payment, order reserves inventory, and payment *emits* an event (the dotted arrow tells a new hire "this is async"). Fields starting with `-` show the repo each service owns. That is the whole onboarding tour.

## Copy-paste 2: interfaces and implementations[​](#copy-paste-2-interfaces-and-implementations "Direct link to Copy-paste 2: interfaces and implementations")

The moment a codebase gets a swappable piece — a payment provider, a storage backend, a notifier — the diagram must show *which* implementation is live. That is what inheritance arrows are for:

```
classDiagram

  %% title: Payment provider — interface and live implementation

  class PaymentProvider {

    <<interface>>

    +charge(amount) Receipt

    +refund(receipt) void

  }

  class StripeAdapter {

    +charge(amount) Receipt

    +refund(receipt) void

  }

  class BraintreeAdapter {

    +charge(amount) Receipt

  }

  class LegacyPayments {

    +charge(amount) Receipt

    +refund(receipt) void

  }

  PaymentProvider <|-- StripeAdapter : active

  PaymentProvider <|-- BraintreeAdapter : pilot

  PaymentProvider <|-- LegacyPayments : deprecated
```

![Payment provider — interface and live implementation](/assets/images/payment-provider-interface-and-live-implementation-eb6063a4259afa83c50d0451b87605a0.svg)

The `<<interface>>` stereotype plus three `&lt;|--` arrows tell the whole deployment story: one interface, three adapters, exactly one marked `active`. When Braintree graduates from pilot, the diagram's edit is one label — and that edit lands in the same PR as the config change.

## Copy-paste 3: the request flow as a thin class diagram[​](#copy-paste-3-the-request-flow-as-a-thin-class-diagram "Direct link to Copy-paste 3: the request flow as a thin class diagram")

Not every architecture question is "what owns what" — sometimes it is "what happens to this request". A class diagram handles that too, with the same classes the code uses but arrows as the call path:

```
classDiagram

  %% title: Public API request flow

  class ApiGateway {

    +handle(req) Response

  }

  class RequestValidator {

    +validate(req) errors

  }

  class AuthFilter {

    +authorize(token) identity

  }

  class OrdersController {

    +post(req) Order

  }

  class Orders

  ApiGateway --> RequestValidator : validate

  ApiGateway --> AuthFilter : authorize

  ApiGateway --> OrdersController : route

  OrdersController --> Orders : read/write
```

![Public API request flow](/assets/images/public-api-request-flow-c672e4174a680666f65b0ab1027ef39c.svg)

This reads like the stack trace developers paste in Slack, but as a *structure*. Pair it with example 1 in the same page — one diagram for who owns what, one for how a request walks through it. Together they cover onboarding and on-call.

## The diagram that keeps up with the code[​](#the-diagram-that-keeps-up-with-the-code "Direct link to The diagram that keeps up with the code")

Mermaid class diagrams stay accurate exactly when you treat them as **reviewed text**, not as a one-time drawing. In [Mermaid Plus for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence/), the macro shows the source below the rendered SVG, so the diagram can be reviewed in the same MR as the code that moves the boundary. A class that changes ownership changes the diagram in the same review that changed the code — the doc drift that rotted your old architecture diagram never gets a chance to start.

That reviewed-text property is the whole point. A class diagram in a wiki that nobody can edit is a wall mural; a class diagram that *is* text is a living map. Keep the boundaries visible, the implementations marked, and the review in the same diff as the code, and the architecture the new hire learns on day one will still be true on day two hundred.

## Where this lives beside your other Confluence diagrams[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to Where this lives beside your other Confluence diagrams")

A class diagram documents the *shape* of the code; other Mermaid types cover the other halves of the story. Keep the class diagram on the architecture page (this post), the ownership and module boundaries), the pipeline that ships it as a flowchart ([CI/CD pipeline diagrams](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md)), and the release history as a gitGraph next to the releases ([branches & releases in Jira](/blog/mermaid-gitgraph-jira-branch-history.md)). Three diagram types, three questions, one space that stays current.

## FAQ[​](#faq "Direct link to FAQ")

**Can Mermaid render a real UML class diagram in Confluence?** Mermaid class diagrams support classes, attributes, methods, inheritance and composition with cardinality comments — close to UML class diagram syntax minus formal stereotypes. Enough to document structure without a UML toolchain.

**How do I show interfaces and implementations?** Use an abstract 'interface' stereotype and inheritance arrows `&lt;|--` — implementations point at the interface they implement. Example 2 shows three adapters under one PaymentProvider.

**How do I avoid a huge unreadable class diagram?** Diagram boundaries, not internals: show the classes at each module's edge and keep internals to a doc comment or a second focused diagram. Readers prefer 8–15 classes per diagram even though Mermaid renders any size.

**How do I keep the diagram matching the code?** Show the Mermaid source under the SVG (Mermaid Plus has that toggle) and review the diagram in the same pull request as the code that changes it — the class diagram then diffs like code.

Render every Mermaid diagram type — class, flowchart, ER, gitGraph, Gantt and 24 more — in [Mermaid Plus for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence/), free for up to 10 users.

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

All 29 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)
* [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.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)
* [class-diagram](/blog/tags/class-diagram.md)
* [architecture](/blog/tags/architecture.md)
* [docs](/blog/tags/docs.md)
* [how-to](/blog/tags/how-to.md)