---
title: "Draw diagrams as code · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/documentation/diagrams-as-code
updated: 2026-10-20
licence: "All rights reserved"
---

# Draw diagrams as code

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Documentation](https://agentwranglers.se/playbook/engineering/documentation)
- Rule: Write diagrams as text in the repository, with a diagram language such as Mermaid, PlantUML or D2, never only as an exported image.
- How: Text diagrams change in the same pull request as the code and show a readable diff. GitHub and GitLab draw Mermaid blocks inside Markdown. Render others to SVG in the build with their command-line tool. Keep one diagram per idea, with at most about 15 boxes.
- Check: The build renders every diagram source with its tool, such as `mmdc` for Mermaid, and fails on a syntax error. A search finds no `.png` or `.svg` diagram without a source file next to it.

Example:

```mermaid
flowchart LR
  shop[Order page] --> api[Orders API]
  api --> db[(Orders database)]
  api --> kitchen[Kitchen screen]
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/diagrams-as-code`.

- Previous: [Test the docs in the build](https://agentwranglers.se/playbook/engineering/documentation/tested-docs)
- Next: [State each value in one document and link to it](https://agentwranglers.se/playbook/engineering/documentation/one-home-per-value)
- [Documentation](https://agentwranglers.se/playbook/engineering/documentation)