Learning PUML for Project Design and Delivery

I stumbled across the “C4 Model for visualising software architecture” via a blogpost I saw on HackerNews back before Christmas and had been waiting for an opportunity to try out the model for myself. I’ve always hated making system design diagrams, probably because I’ve always found it:

  • time consuming;
  • impossible to meaningfully track changes.
  • difficult because I lacked appropriate tooling and an methodological framework and;
  • boring.

I liked what I saw in the above links because it addressed the first three problems I had: I could cut down how long it took to make diagrams by writing PUML code, track changes in a git repository, and configure VSCode with plugins to generate the images and relationships programmatically for usage in documentation/wikis. And because it meant I could write my diagrams in code, it fixed the 4th problem and now, I actually enjoy making diagrams.

I now use the Vscode PlantUML Plugin which on linux also required the installation of graphviz:

sudo apt install graphviz -y

And after some basic configuration to get the plugin working it becomes quite easy to work on creating diagrams.

!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(personAlias, "Label", "Optional Description")
Container(containerAlias, "Label", "Technology", "Optional Description")
System(systemAlias, "Label", "Optional Description")

Rel(personAlias, containerAlias, "Label", "Optional Technology")

Screenshot of VScode:

VSCode and rendering plugin

Obviously I cannot include any of the diagrams I’ve made for work here on my blog, so I’ve used code and examples from the Git repository for the C4 Model instead. The repository includes everything you need to generate visually pleasing models. I found that after a few days of using the examples in the repo, I’ve been able to make quite useful diagrams for our new file transfer system I’ve been designing at work that  illustrates the system we’re designing and building. The C4 Model repository also makes use of another repository of images/sprites which I’ve utilised to add some flair and comprehensibility to the diagrams.