C4 diagrams in Confluence

A C4 diagram describes software at a chosen level of detail: context, containers, components or deployment.

Last updated

When to use it

Use a C4 diagram when different readers need different depths. The context view shows users and neighbouring systems for anyone; the container and component views go one level down for the engineers who build it. Every element carries a name, a technology and a short description.

Example

This is the code of the System context template: users, the platform and its external systems in one C4 view.

C4Context
  title System context for a SaaS platform
  Person(customer, "Customer", "Manages a subscription and its billing")
  Person(admin, "Administrator", "Configures tenants, users and plans")
  Enterprise_Boundary(company, "Company") {
    System(platform, "SaaS platform", "Serves customers and administrators")
  }
  System_Ext(payments, "Payment provider", "Charges cards and issues refunds")
  System_Ext(email, "Email service", "Delivers transactional email")
  System_Ext(idp, "Identity provider", "Authenticates users with single sign-on")
  Rel(customer, platform, "Uses", "HTTPS")
  Rel(admin, platform, "Manages", "HTTPS")
  Rel(customer, idp, "Signs in", "OpenID Connect")
  Rel(platform, idp, "Verifies tokens", "OpenID Connect")
  Rel(platform, payments, "Charges cards", "REST / JSON")
  Rel(platform, email, "Sends email", "SMTP")
  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Vellnar Diagrams draws it like this:

Change a line and the diagram changes with it. Nobody needs the original drawing file, because there is none: the code is the diagram.

Add it to a Confluence page

  1. Edit a Confluence page and type /mermaid where the diagram should go.
  2. Select Mermaid diagram. The editor opens with the template list.
  3. Pick a template, or choose Start blank and paste the code above. The preview follows every keystroke.
  4. Choose Save. The diagram appears on the page.

The documentation covers the editor, the settings and the exports.

Templates

The Templates button in the editor has 2 C4 diagrams ready to use:

  • System context: Users, the platform and its external systems in one C4 view.
  • Event streaming: A partitioned topic, its consumer groups, a dead-letter topic and a schema registry.

Syntax

The code of a C4 diagram starts with C4Context. The Mermaid documentation describes every element of the syntax. Vellnar Diagrams draws it with Mermaid 12.3; if a line has an error, the editor marks the line and keeps the last valid diagram on screen.

More

  • Mermaid in Confluence: how diagrams as code work in a page, and every diagram type.
  • Security: the app asks for no permissions and sends nothing outside Atlassian.