Diagrams as Code

Have you ever started working on a new project, started going through the documentation and you realize that the architecture diagrams or sequence diagrams are out of date.

I've certainly seen this situation arise numerous times in my career so far. So what do you do? One solution would be whoever's reading the document needs to do the work to figure out the updated architecture or flows and generate the new diagrams using UML tools. This isn't ideal and these are bound to get stale again in the future.

Another solution which I prefer is - maintaining diagrams as code which live in the same repos as the code. There are many tools these days which help us author diagrams from code.
My favorites are Mermaid and PlantUML.
Now your code can live in the repo and evolve along with the codebase. You might need to do additional setup if you'd like the diagrams to be generated as part of your CI/CD.
I like to maintain these in a /docs folder within the project repo.

An example of how the code would look like in mermaid and it's output are below:

Code:

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

Output:

Bonus: Mermaid.js has built in support in GitHub for markdown files. You won't need to do anything special to generate diagrams here.

That's it, what's your take on these? Do you know any tools which offer better options or more customization? Leave a comment 😄 !

Comments

[Aaron Reese]

+1 for mermaid. I used a graphical workflow builder (think Microsoft Flow but in Windows 3.1 :) ) which stores it's steps in a database but had no proper visualisation tools. I wrote a script to generate Mermaid.js notation so we could see the whole process.

[Nash]

Agreed tools like these work great, I use them myself (PlantUML, Kroki, etc.). The challenge is standardizing it across your team/enterprise. They work great when you have simple flows and want to generate the diagrams dynamically. But for general and complex use cases alternatives like draw.io and lucidchart that are integrated into Notion, Confluence and others, are preferred especially by non dev community.