Skip to main content

Document a system architecture in Confluence

Build an architecture page that shows how your services connect, how a request flows through them, and how the system fits into its surroundings.

Problem: Architecture diagrams live in drawing tools and go stale. Nobody redraws the boxes when a service is added, so the page soon shows a system that no longer exists.

Solution: Write each diagram as Mermaid code in a Mermaid Diagram macro. A change is a one-line edit that anyone who can edit the page can make.

An architecture page with cloud service icons drawn by Mermaid Diagrams

What you'll need​

  • Mermaid Diagrams Macro for Confluence, installed on your site. See Get started.
  • Permission to edit the page.

Set it up​

1. Draw the services​

  1. Open the page, select Edit, and type /mermaid where the diagram should go.

  2. In the macro, select Create diagram, then Start from a snippet > Architecture with Icons > Insert.

  3. Replace the services with your own. Each service line is one box, and group draws a frame around boxes that belong together:

    architecture-beta
        group cloud(logos:aws)[Payments platform]

        service gateway(logos:aws-api-gateway)[API Gateway] in cloud
        service checkout(logos:aws-lambda)[Checkout service] in cloud
        service db(logos:aws-aurora)[Orders DB] in cloud
        service web(mdi:web)[Web shop]

        web:R --> L:gateway
        gateway:R --> L:checkout
        checkout:B --> T:db

    Icons come from two built-in sets: logos: for cloud and technology logos, and mdi: for general icons such as mdi:server or mdi:database. Find names at icones.js.org. An unknown name shows a question mark.

  4. Under Display size, select Large, then select Save and close.

2. Show how a request flows​

  1. Add a second macro under a heading such as "Order flow".
  2. Select Create diagram > Start from a snippet > Sequence Diagram: API Flow > Insert, and change the participants and messages to your own.
  3. To keep a simpler overview next to it, select Add diagram > Blank diagram and write a short flowchart. Readers page through the two diagrams with the arrows next to 1 of 2.
  4. Select Save and close.

3. Place the system in context​

  1. Add a third macro and insert the C4 Context Diagram snippet.
  2. Name the people and outside systems your platform works with, then select Save and close.
  3. Publish the page.

Check that it works​

  1. Open the published page as a reader would.
  2. Hover over a diagram and select Open full screen. Zoom in on a dense area to check that labels are readable.
  3. Ask a teammate to change one label with Edit diagram. The change shows for everyone as soon as they save.
tip

Keep each diagram to one idea. A page with three focused diagrams is easier to read and to update than one diagram with 60 boxes.