Setting up PlantUML for coding C4 architecture diagrams

Background

Earlier there was a post in this blog related to documenting architecture using C4 Architecture model. The architecture of www.joymononline.in is documented in the C4 way. At least, the context diagram. The problem what was tried to solve in that post was how to make code inline with architecture.

It is easy to document architecture for a static portfolio site or a simple CRUD operations site with a login feature. But difficult in Enterprise systems especially, if the rate of change is so rapidly. Nowadays the software is changing its happening at high speed with the advent of DevOps culture and practices such as continuous integration, delivery, monitoring, etc...

Problem

When we follow any documentation model as a technical person, we may face below problems

• Versioning with application code.
• What if a feature branch changes the architecture or component interaction or alters dependencies
• Comparing what changed from the last version?
• The time-taken to beautify the diagrams. Skills depend on person to person and difficult to get it uniform when the organization grows.

Potential solution

One way we could apply is coding the architecture. Meaning, store the architecture diagrams in textual representation and store along with code. Generate diagrams out of it. It is a simple idea similar to using markdown for documents. It's human and machine-readable.

Let's see one way to document the C4 architecture model using textual language. First introducing of some terms and later see how they are smartly glued to get coded C4 architecture diagrams.

PlantUML

This is a text-based UML modeling. This has specs and free to use. It has also Java-based rendering mechanism which uses another free software called GraphViz to visualize the diagrams.

GraphViz

This is a visualization tool for creating diagrams. Its open-source. This is needed by PlantUML to render charts.

VS Code & PlantUML extension

This is the developer's favorite editor. As usual, there is an extension to easily write and preview the diagrams. The name of the extension is 'plantuml'. We can either install via extension editor or by command. Thanks to the author Jebbs for the extension and making open source.

How to setup VS Code for PlantUML is already mentioned in the below link. Since we are living in the 21st century, the Japanese language in the post can be converted automatically by the browser to English:)

https://ameblo.jp/sijukara-tama/entry-12445811317.html

C4-PlantUML GitHub repo

The magic is here. Below repo has the C4 customization files for PlantUML to understand the C4 language.

https://github.com/RicardoNiepel/C4-PlantUML

Big thanks to Ricardo for his work and especially for open-sourcing the same. The repo has enough details about the capabilities and sample to get started.

Another interesting thing he did is the availability of Azure customization. These files help us to create diagrams using Azure symbols than boring boxes.

https://github.com/RicardoNiepel/Azure-PlantUML

Troubleshooting

Though some of us get the environment working in the first attempt itself, I am trying to do a video (my first tech video) on how to set up the environment for doing C4 architecture of www.joymononline.in via PlantUML notations and the tools mentioned above

If we go step by step there will not be any issues. Below are the steps

1. First, install Java. That will make sure the PATH variable is set properly.
2. Then install GraphViz. Even there is no issue installing in a different order as those are not dependent. 
3. Now install the VSCode and 'plantuml' plugin. the plugin contains the plantuml.jar file. 
4. Finally, download the customization from C4-PlantUML repo and open in VS Code. 
5. Check the preview by Alt+D shortcut.

Once we have the environment setup its easy as typing the diagram and previewing it in the same window. Commit the file once ready. Better integrate with the build pipeline.

Conclusion

The mix of specs & tools is little complex but easy to set up and use. Though there is no support for the tools we as developers can fix the issues and add features in those tools and give back to the community