Diagrams as code 2.0

Diagrams as code is becoming a popular way to diagram software architecture, particularly for long-lived high-level documentation. You write the diagram source in a text-based domain specific language (e.g. PlantUML, C4-PlantUML, Mermaid, WebSequenceDiagrams, Graphviz/DOT) or a programming language (e.g. Diagrams), and render diagrams using web-based or command line tooling. The benefits are well understood - writing the diagram source as text allows for easy integration into software development practices and toolchains, plus the automatic layout facilities allow authors to focus on content.

But there's a problem with this approach, which I'm going to call "diagrams as code 1.0" - if you need to create multiple diagrams, you need to create multiple diagram source files, and ensure that you keep these files in sync.

Some tools do provide a way to "include" snippets, but most don't, forcing you to repeat information across those diagram definitions. Once you violate the "DRY principle", you need to ensure that any changes you make to one diagram are reflected elsewhere. Easy in theory ("we'll just use global search and replace", etc), but that doesn't necessarily happen in the real world.

One way to resolve this problem is to generate multiple diagrams from a single source file. To do that, we need to shift our thinking away from "diagrams", and towards "views of a model". That's the essence of "diagrams as code 2.0" - it's a way to define a model of our software architecture and the views that we'd like to see, ultimately resulting in a consistent set of diagrams that are generated for us.

This is the concept implemented by the Structurizr tooling, the majority of which is open source. Structurizr builds upon "diagrams as code", providing a way to create multiple diagrams from a single model, using a number of tools and programming languages. There are three key concepts:

1. Workspace - this is the definition of the model and views, described using an open JSON format.
2. Authoring tools - these provide a way to create a workspace. The most popular is the text-based Structurizr DSL.
3. Rendering tools - these provide a way to render the views as diagrams. Supported diagram formats include PlantUML, C4-PlantUML, Mermaid, DOT, WebSequenceDiagrams, Ilograph, and the Structurizr cloud service/on-premises installation.

The separation of authoring and rendering reduces lock-in to any particular diagramming tool. And having a model of your software architecture provides a way to slice and dice it to create many different views, which can then be rendered using the best tool for the task ... a static PNG, an interactive and zoomable SVG, or perhaps an interactive force-directed graph.

Summary

To summarise the key differences:

• Diagrams as code 1.0: you write diagram definitions by hand
• Diagrams as code 2.0: diagram definitions are generated automatically, by tooling, based upon views of a model

Although many teams define their models by hand, there's nothing preventing you from generating the model automatically, in part or in whole, by parsing infrastructure as code definitions, parsing distributed log files, performing static analysis of a code base, etc. Such techniques are especially useful for teams seeking ways to diagram their larger and more complicated distributed architectures.