Mermaid Diagrams, PlantUML and C4: Diagrams as Code

1. What diagrams as code means

Diagrams as code are diagrams described in a text syntax that a tool turns into an image. Instead of dragging boxes around with your mouse, you write "api --> db" and the tool takes care of the layout and the connections.

The real difference is where you maintain the diagram. A diagram file on a shared drive or an image exported somewhere into the docs stops matching the code over time and it's rarely clear who should update it and when. A text diagram in the repository, on the other hand, gets reviewed together with the change it describes, and the diff shows what changed in it.

2. Mermaid diagram syntax that GitHub and GitLab render

Mermaid is a JavaScript library that renders flowcharts, sequence diagrams, database ER diagrams, state diagrams, Gantt charts and more from plain text. According to GitHub's docs, you just put the diagram in a code block marked mermaid in any Markdown file, issue or pull request. GitLab renders it the same way.

You can try the syntax in the Mermaid Live Editor, which shows a preview as you type. Notion, Obsidian and Azure DevOps wikis display Mermaid too. The Mermaid flowchart below shows the architecture of a small web app.

```mermaid
flowchart LR
  customer([Customer]) --> web[Web app]
  web --> api[API]
  api --> db[(PostgreSQL)]
  api --> payments[Payment gateway]
  api --> email[Email service]
```

3. PlantUML: every UML diagram type

PlantUML is a Java tool that covers all the common UML diagrams (sequence, class, use case, component and deployment) plus extras like UI wireframes. A diagram starts with @startuml and ends with @enduml.

GitHub doesn't render PlantUML directly, but GitLab.com does. On a self-managed GitLab instance, an admin has to enable it. Locally, a VS Code or IntelliJ extension shows a preview. Without installing anything, use the PlantUML online server at plantuml.com. Here's a sequence diagram for placing an order.

@startuml
actor Customer
participant "Web app" as Web
participant API
database PostgreSQL as DB
participant "Payment gateway" as Payments
Customer -> Web: Place order
Web -> API: POST /orders
API -> DB: save order
API -> Payments: create payment
Payments --> API: payment URL
API --> Web: 201 Created
@enduml

4. Mermaid vs. PlantUML

For most teams on GitHub, Mermaid is the default choice because GitHub supports it out of the box. PlantUML is worth it when you need UML diagrams Mermaid doesn't handle well or you already use it in GitLab.

5. The C4 model: architecture at four zoom levels

The C4 model describes software architecture at four zoom levels: system context, containers, components and code. A container here isn't a Docker container. It's any separately deployable part of the system, like a web app, an API, a database or a mobile app.

The C4 model, created by Simon Brown, isn't a tool but a method for describing architecture with diagrams. You can draw them in Mermaid, in PlantUML or in a dedicated tool like Structurizr. Most apps only need the first two levels. A component diagram pays off for the larger parts of a system.

6. Which architecture diagrams you actually need

The diagrams worth maintaining are the ones that help people understand processes, structures, relationships or events in the system. With generative AI, it can look like long written descriptions and explanations are what matters, but people grasp a diagram much faster than a page of text. In a typical web or mobile app, that's usually five types, linked from your project documentation.

You usually don't need to maintain class or use case diagrams by hand. Your IDE can show a class diagram from the code and agile teams write use cases as user stories. If a tender requires them, create them for that specific release and don't update them afterwards.

7. Without Mermaid: draw.io files and AI-generated diagrams

If text syntax isn't your thing, have AI create the diagram in draw.io. A .drawio file is actually XML, so an assistant like Claude Code, Codex or GitHub Copilot edits it like source code: it changes only the element you ask for and leaves the rest of the diagram alone. draw.io offers an official MCP server and plugins for AI assistants and its editor has a built-in tool that can generate a diagram from a description.

In the repository, you can use the .drawio.svg or .drawio.png format. Both are regular images that GitHub shows, for example in a README. Because they also contain the XML data, the Draw.io Integration extension for VS Code can open them for editing with no export step.

AI models like ChatGPT or Gemini can also create a software architecture diagram as an image and let you edit just selected parts of it without regenerating the whole diagram. That kind of diagram works well for presentations or for a client, because you can easily add infographics, photos and more. The downside is that an image is a binary format, so Git can't track partial changes: the whole file changes every time.

8. Where architecture diagrams should live

Diagram source files belong in the repository, typically in the docs folder, but you can also keep them in documentation tools like Confluence, MediaWiki or Notion. Developers aren't the only ones who need diagrams. Other roles in the app's lifecycle do too: an analyst, a project manager, a tester, the client or a new vendor during a project handover.

In AboutTheApp, you attach a link to the diagrams folder or to the documentation under Source Code & Architecture and process diagrams from analysis under Analysis & Planning. Links not everyone should see can be marked private. If a client runs their own deployment with different infrastructure, you attach their deployment diagram to their installation only and it shows up on their About page. AboutTheApp doesn't render diagrams, it keeps the links to them.

Frequently asked questions