Diagram as Code Explained: Tools, Workflows, and AI in 2026

Diagram as code (DaC) is the practice of writing diagrams as plain-text files in a domain-specific language and rendering them automatically into images. Instead of dragging shapes in a visual editor, you write text like graph LR; A-->B and a renderer produces the diagram. The text file lives in version control alongside source code, which makes diagrams reviewable in pull requests, diff-able across changes, and never out of date with the system they describe. Engineering teams adopt diagram-as-code for the same reasons they adopt infrastructure-as-code: reproducibility, peer review, and a single source of truth.

The diagram-as-code movement has accelerated since GitHub started rendering Mermaid diagrams natively in markdown. Notion, GitLab, Azure DevOps, and most modern documentation platforms now render at least one diagram-as-code language inline. AI generators add a new dimension: you can describe a system in plain English and get the diagram-as-code output ready to paste into a README or commit to a repo.

Why teams adopt diagram as code

• Version control - diff diagram changes line-by-line in pull requests, the way you would for any code change
• Single source of truth - the rendered image is generated from the text file. There is no chance of the "source" and the "published" versions drifting apart
• Reusability - shared partials, includes, and templates let you reuse common components across diagrams
• CI/CD integration - regenerate diagrams in CI, fail builds on syntax errors, deploy updated diagrams alongside the application
• AI compatibility - LLMs read and write diagram-as-code natively because it's just text. Visual editors require image-to-shape recognition that is far more error-prone

The major diagram-as-code tools

How each tool feels in practice

Mermaid

Mermaid is the path of least resistance. Write a flowchart in 4 lines, commit it to a markdown file, and GitHub renders it inline. Best suited for flowcharts, sequence diagrams, ERDs, and class diagrams. Custom styling is improving but still limited compared to D2.

PlantUML

PlantUML is the venerable choice. It supports the full UML spectrum - sequence, class, activity, state, deployment - plus C4 diagrams via a community library. The aesthetic is dated by default but theming helps. Confluence plus the PlantUML add-on is a common enterprise setup.

D2

D2 (Declarative Diagramming) is a newer entrant designed around modern aesthetics and ergonomics. The output looks far more polished out-of-the-box than Mermaid or PlantUML. D2 supports inline SQL-style connection syntax, custom shapes, and a powerful theming system.

Structurizr DSL

Structurizr is purpose-built for the C4 model. You describe your software architecture once in the DSL and Structurizr generates the Context, Container, and Component diagrams from a single source. Best for large organisations standardising on C4.

Diagrams (mingrammer/diagrams)

Diagrams takes a different angle: you write Python that constructs an architecture graph using AWS, Azure, GCP, and Kubernetes shape libraries. The result is a polished PNG. Best when your stack is already cloud-heavy and you want diagrams generated from Python infrastructure tooling.

AI plus diagram as code

AI accelerates diagram-as-code in three ways:

1. First draft generation

Describe your system in plain English; the AI emits Mermaid, PlantUML, or D2. You commit the text file and let the renderer take over from there. This collapses the highest-friction part of diagram-as-code - learning the syntax for the first time.

2. Refactoring diagrams

Ask the AI to restructure an existing diagram - extract subgraphs, rename participants, change orientation, convert from one notation to another. Because the diagram is text, the AI can reason about it directly.

3. Translating between tools

AI converts cleanly between diagram-as-code languages. A Mermaid sequence diagram can be translated to PlantUML, D2 to Structurizr, and so on. This makes lock-in less of a concern when picking a tool.

When NOT to use diagram as code

Diagram as code is excellent for diagrams that live alongside source code. It is less ideal for:

• Pixel-perfect diagrams for executive decks - when layout precision matters more than reproducibility, a visual editor still wins
• One-off whiteboard sketches - the syntax overhead isn't worth it for diagrams you'll throw away
• Highly custom illustrations - if you need bespoke shapes, gradients, or icons, a vector editor like Figma is more flexible

A practical workflow

1. Pick one tool and stick with it for the team. Mermaid is the safest default in 2026 because of GitHub native rendering.
2. Store diagrams next to the code they document. Mermaid lives inline in markdown files; PlantUML/D2 in a docs/diagrams/ folder.
3. Generate first drafts with AI when starting from scratch, then edit the text file directly for refinements.
4. Render diagrams in CI to catch syntax errors before they ship.
5. When the system changes, update the diagram in the same pull request as the code change.

Frequently asked questions

Is diagram as code only for software architecture?

No. Mermaid, PlantUML, and D2 all handle flowcharts, ERDs, sequence diagrams, gantt charts, and more. The approach generalises beyond software.

Can non-engineers use diagram as code?

With AI assistance, yes. The traditional barrier - learning DSL syntax - is largely removed when you can describe the diagram in plain English and let the AI generate the code.

Should I learn Mermaid or PlantUML first?

Mermaid. It has lower syntax overhead, better native rendering support across the modern documentation stack, and a growing ecosystem. PlantUML is still the right choice if you're embedded in a Confluence-heavy enterprise or you need full UML coverage.

Try it

See Mermaid vs. traditional diagramming, the C4 model, or open ArchitectureDiagram.ai and pick Mermaid as your output format.