Architectural Diagrams Made Easy

A picture is worth a thousand words, an architectural diagrams help convey complex information in a single image.

• Architectural diagrams show systems. Displaying information visually allows the viewer to see everything at a glance, including how elements interact. This is especially useful when making changes. You’ll be able to see the downstream effects of a given change more clearly.
• Architectural diagrams also break down complex systems and processes into layers. So, rather than trying to comprehend everything at once, you can zoom in and focus on smaller sub-processes or systems.

One of the main issues software engineers face is consistency. When you’re working on anything that involves multiple people, there’s always a risk of miscommunication and discrepancies between project teams and developers. It’s crucial to standardize information, which is where an architectural diagram becomes helpful.

There are lot more ways to create architectural diagrams. If you search in Google it will pull you few thousand results on how to create an architectural diagram. The method we discuss here is a GitHub project repository called “diagrams” created by Min-Jae Kwon. This is an opensource project released with MIT license. Diagrams lets you draw the cloud system architecture in Python code. It was born for prototyping a new system architecture design without any design tools. A Golang fork is also available here for those who are familiar with go.

Diagrams requires Python 3.6 or higher, check your Python version first.

We can start with updating pip3 itself before we install diagrams

/usr/bin/python3 -m pip install --upgrade pip

pip3.7 install diagrams

Diagrams uses Graphviz to render the diagram, so you need to install Graphviz to use diagrams.

sudo apt install python-pydot python-pydot-ng graphviz

We’ll now have a working diagrams tool installed and let’s see how we can use it.

Open any IDE and type in the below code and save as a .py file.

from diagrams import Diagram
from diagrams.aws.compute import EC2

with Diagram("Simple Diagram"):
    EC2("web")

Diagram represents a global diagram context.

You can create a diagram context with Diagram class. The first parameter of Diagram constructor will be used for output filename.

And if you run the above script with below command,

python diagram.py

It will generate an image file with single EC2 node drawn as simple_diagram.png on your working directory, and open that created image file immediately.

In the example described here I’m using Jupyter Notebook to create diagrams with ‘Diagrams’/ The per-requisite is to have Jupyter notebook installed on your system which runs on localhost:8888
Installation & configuration of Jupyter Notebook is pretty straight forward in Linux and is out of scope for this post. You can do a Google search and follow any documentation/blog post for that. Diagrams can be also rendered directly inside the notebook as like this:

from diagrams import Diagram
from diagrams.aws.compute import EC2

with Diagram("Simple Diagram") as diag:
    EC2("web")
diag

You can specify the output file format with outformat parameter. Default is png. Saving output as png, jpg, svg, and pdf are allowed.

from diagrams import Diagram
from diagrams.aws.compute import EC2

with Diagram("Simple Diagram", outformat="jpg"):
    EC2("web")

I’m still exploring more on this GitHub project. I’ll post another post later with details on system design with more option available with this awesome tool.

For a quick demo please check the video posted below

«Site Reliability Engineering (SRE)»Fun with Linux CLI