Diagrams as Code

When a system grows, there is a time when team needs to document the different components involved and how they are connected. A diagram is the best way to do this and it offers a first global sight of the whole system or a part of it.

Diagrams are useful in many ways: they help detecting improvements in the architecture or infrastructure, they help new team members to understand how everything is done and, last but not least, they reduce the mental burden of the team.

There are many tools to draw diagrams. Many of them are WYSIWYG tools, e.g. Excalidraw, Draw.io and Lucidchart. With these tools, you drag and drop boxes and arrows to the canvas. And, in some of them, you can export the diagrams as XML or JSON files. They are easy to use but they are not developer oriented or even developer friendly; diagrams are not made from code or semantical software concepts (like server, database or whatever...) but from graphical elements (arrow, line or polygon). As developers, we don't care about cylinders and cubes but rather databases and virtual machines.

And that's the reason why Diagrams as Code (DaC) technique does exist. DaC tools are focused on semantical stuff instead of graphical stuff.

Tools like Structurizr implement this principle. With them, you can create diagrams by writing code and and it already contains built-in concepts like database, file system or application. Structurizr uses its own DSL. Also, it supports being used as a library in some programming languages like Java or C#. Another example is Diagrams. A Python library that lets you draw diagrams from Python code. Here are some cool examples.

Since DaC diagrams are text-based rather than binary-based, it is easy to integrate them in source control management tools and deployment pipelines and take advantage of that, for example, by using PRs to make changes in the diagram and automatically render and publish them to online documentation tools.

If you need to document your system, consider using this approach the way fits your team better.