What is diagram as code and how can I start on it?

Diagram from code

What would you say If I tell you that the above diagram was crafted with code?

So, maybe you could think: “It’s overkill!", “Oh, man! Another mainstream tool”. And that’s ok, to be honest, that’s what I thought at the first time, however after some thinking and reading the approach behind that, It made sense to me.

Last November, I read the whole report of Technology Radar by ThoughtWorks (which I highly recommend taking a look at), and one of the new or trial techniques was “Diagram as Code”. The concept is to have a tool that allows creating diagrams (eg. architecture diagrams), via code.

So far, sounds great, but why that? Since many applications on the market allow us to do that easily just using our mouse.

In my opinion, It has good advantages such as:

Versioning with your code. You know that version control systems are good for text files but not for binaries, so It’s a good way to track changes in your architecture or flow (expressed in your diagram).
Delete dependencies with programs. Due to you’re going to build your diagrams with code, the only thing that you’ll need would be your compiler or interpreter.

Ok, looks promising, but how can I start creating my diagrams with code?

If you check the report that I mentioned previously, you’re going to find several options, however, during my research, I found one which I liked because of good documentation and its community, Diagrams.

Basically, with Diagrams, you can draw system architectures or simple diagrams using Python. So, you will need Python 3.6 or higher, Graphviz and that’s all.

Let’s have fun

Disclaimer: I don’t pretend to make a tutorial about the installation process and usage, because they explain excellently, so, I encourage you to check its documentation.

Nonetheless, what I want to explain here is my experience during my learning process, so, you can take it as a reference to determine if It’s a good alternative to try. So, for that purpose, I decided to use an AWS diagram that I saw a time ago as a reference (Here, you can find the diagram about an AWS architecture).

The key points that I wanted to cover are:

Learning curve: Is it easy to learn and can I start crafting diagrams just taking the documentation as a reference?
Customization / Flexibility: I desire to know If I can re-draw current diagrams and If I can represent any component with Diagrams.
Resource consumption: One of the main problems with desktop programs is the hardware issue, some of them start running slow when the diagram is too big.

Learning curve

For this point, I can say, It’s pretty straightforward! Whether you know how to code in Python or not, you can commence creating diagrams, just following the examples in the documentation. In my case, owing to I chose a diagram that contains on-premises and AWS components, I spent some time searching how to build custom items, however, I was able to craft the diagram above, in 40-45 mins, so It’s good (in my opinion) since It’s the first contact with that tool.

Customization

That was my main concern because in the vast majority of cases you’re going to craft complex or not ordinary diagrams, even so, I noticed the tool allows to create any kind of component. Therefore, I’d like to answer some questions that I had.

Which kind of diagrams can I craft?

Any type, however, Diagrams has a focus on cloud, so you can find out-ot-the-box icons/nodes about AWS, Azure, GCP, K8S, AlibabaCloud, OCI, OpenStack, Firebase, Outscale, Elastic, and other generic components such as operating systems and programming languages

What can I do If my component/icon doesn’t exist?

In my case, I had to set 3 different types of components, AWS components, on-premises components, and text boxes explaining custom components. For the first ones It was simple, I just needed to use defined classes in the tool. For the second one, I used on-premises components and create custom ones using external images. And the last one, I just wrote some HTML code and embedded it into the custom component.

However, If you cannot figure out how to craft your components, I suggest taking a look into GitHub’s issues, where you going to see different questions and solutions about that.

Resource consumption

It’s fast! You might be noticed the above diagram is small, but I added more clusters and components to that one, just to test the performance and time It takes to generate, and just take few milliseconds, no complaints at all.

Conclusions

In summary, this is an excellent tool, because you are going to be able to track any changes in your diagrams, the learning curve is low and, to be honest, I like the idea to craft diagrams using code.

In the end, It’s a new tool that you can check and decide if that fits your workflow. So, in case you want to go deeper, you can review the code that I made to generate the diagram that I showed here.