Document Your Codebase in Confluence with Mermaid Class Diagrams
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 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
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
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
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
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
The <<interface>> stereotype plus three <|-- 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
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
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
Mermaid class diagrams stay accurate exactly when you treat them as reviewed text, not as a one-time drawing. In Mermaid Plus 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
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), and the release history as a gitGraph next to the releases (branches & releases in Jira). Three diagram types, three questions, one space that stays current.
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 <|-- — 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, 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