# Diagrams as Code

**In short:** Diagrams as code means writing architecture diagrams as plain text. A toolchain renders the text into pictures. Teams can then store, compare, and build diagrams like source code.

## Explanation

Many diagramming tools save diagrams in formats that are hard to compare. That makes version control awkward. Plain-text diagrams avoid this problem, because a change shows up as a change in text.

**Text embedded in documents.** Asciidoctor Diagram is a set of extensions for Asciidoctor, a tool that builds AsciiDoc documents. It renders plain-text diagrams from inside those documents. To do this, it calls external renderers.

**One model, many views.** A second approach starts from a model, not from single drawings. A modelling tool builds a non-visual model of the software architecture. Pure drawing tools only produce boxes and lines. A model helps keep diagrams consistent with each other. See Modeling Tool vs. Drawing Tool and Model vs. View.

Structurizr DSL follows this approach. It is a text language that creates diagrams from one consistent model. A workspace has these parts:

- A `model` block. It is required. It defines elements and relationships.
- A `views` block. It holds one or more views. Defining any view removes the default set.
- A `styles` block. It sets how elements and relationships look.

Layout can be automatic. You add the `autoLayout` statement inside a view.

**Renderers differ.** Structurizr DSL diagrams can go through external PlantUML, Mermaid, or Kroki services. These produce png or svg output. Some styles are made for the Structurizr tools. PlantUML or Mermaid exports may not support them fully. See Kroki.

**Keeping diagrams current.** One published example generates its views from a single Structurizr model as C4-PlantUML diagrams. It regenerates them before the documentation build. The reasoning is that diagrams should be generated from code automatically, to reduce manual effort.

## Example

A team keeps one text file that describes its system: a web shop, a payment service, and the links between them. The file defines two views, an overview and a detail view. Before each documentation build, a script renders both views into images. When the team renames the payment service, it edits one line. Both views update on the next build. A reviewer sees the rename as a small text change in the pull request.

## Trade-offs

The facts support one clear benefit. Text diagrams are easy to compare and version, and a single model keeps views consistent.

The facts also show a cost. Renderers do not support every style equally, so the same model can look different in the Structurizr tools, PlantUML, or Mermaid. Automatic layout is optional, which suggests that placing elements takes extra care.

One text model produces several views, which a renderer turns into images for the documentation.

```mermaid
flowchart LR
  M[Architecture model as text] --> V1[Context view]
  M --> V2[Container view]
  V1 --> R[Renderer]
  V2 --> R
  R --> I[png or svg images]
  I --> D[Documentation build]
```

## Checks

- Diagrams are stored as plain text in version control, not only as binary or hard-to-compare files.
- Views are generated from one shared model, so the diagrams stay consistent with each other.
- Generated diagrams are regenerated automatically before the documentation build.
- The document states which renderer produces the diagrams, and styles are checked against that renderer.

## Related

- [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md)
- [Modeling Tool vs. Drawing Tool](https://arc.fuet.ch/concepts/modeling-uml/modeling-tool-vs-drawing-tool.md)
- [Model vs. View](https://arc.fuet.ch/concepts/documentation/model-vs-view.md)
- [C4 Model](https://arc.fuet.ch/concepts/documentation/c4-model.md)
- [Kroki](https://arc.fuet.ch/concepts/documentation/kroki.md)
- [Diagram Metadata in PNG (drawio.png)](https://arc.fuet.ch/concepts/documentation/diagram-metadata-in-png-drawio-png.md)
- [Architecture View](https://arc.fuet.ch/concepts/documentation/architecture-view.md)
- [Self-Documentation](https://arc.fuet.ch/concepts/documentation/self-documentation.md)

## Sources

- [Tooling | C4 model](https://c4model.com/tooling) — c4model.com, accessed 2026-11-09
- [Overview | Asciidoctor Docs](https://docs.asciidoctor.org/diagram-extension/latest/) — docs.asciidoctor.org, accessed 2026-11-09
- [Cookbook | Structurizr](https://docs.structurizr.com/dsl/cookbook/) — docs.structurizr.com, accessed 2026-11-09
- [Language reference | Structurizr](https://docs.structurizr.com/dsl/language) — docs.structurizr.com, accessed 2026-11-09
- [Structurizr & C4-PlantUML: Architecture as Code](https://www.codecentric.de/en/knowledge-hub/blog/architecture-documentation-as-code-with-structurizr-and-asciidoctor-part-3-structurizr) — codecentric.de, accessed 2026-11-09