Introducing Diagrams

A python library for “Diagrams as Code”

Photo by Florian Krumm on Unsplash

As a software developer there is a high probability that you would have created a presentation, wiki or some other asset to document your architecture. And one of the key component is diagrams. You could have generated a UML class diagram to show your design or a deployment diagram for your cloud deployment.

But the problem with these diagrams is that once done, mostly it’s never revisited and updated. Your architecture or design evolves over time. Code, infrastructure and every other component gets updated but not your original architecture diagram unless there is significant change. I’m guilty of this as much as the next software developer.

The velocity of changes to a software system has increased with Cloud and Micro services and because of that we have started treating Infrastructure as Code to ensure that your infrastructure provisioning can be versioned and made repeatable and less error-prone. There are tons of changes that keep happening to the infrastructure, addition of database replicas for handling query loads, new compute added, services onboarded etc. But the diagrams are left behind.

Enter Diagrams

It’s an open source python library and as it says on the website

It’s leverages graphviz to render the diagrams. The diagrams are directed graphs provided by graphviz. To install the library, (other pre-requisites and steps can be found here)

pip install diagrams

It supports all major cloud vendors and also has very good support for on-premise infrastructure as well.

Let’s create a diagram for a simple web services deployment in AWS. Where 3 instances of a container are running on ECS with backend DB’s in RDS.

Once you execute the code, it generates a .png file(see below) in the current working directory. Other output formats like jpg, svg are also supported.

Log Search Application

Let’s say you want to design a log search system, which indexes logs from S3 into elasticsearch and exposes a set of API’s and nice SPA as UI.

Now the image is generated top-to-bottom instead of left-to-right and there are lot of other graph related attributes that can be tweaked as well.

So now let’s say we have a terraform script which does all the infrastructure provisioning for this application and when we change that we can also update this python script to reflect the latest changes to the stack. This ensures the diagrams are also versioned and kept up to date.

We can also further automate things by generating diagrams by connecting to existing cloud infrastructure or even parse descriptors like CloudFormation or terraform in json format.


Software Engineer | Passionate Learner | Lifelong Student