Diagrams/Architecture as a Code

Reading Time: 3 minutes

We’re seeing more and more tools that enable you to create software architecture and other Diagrams as Code. The main benefit of using this concept is that majority of the Diagrams as Code tools can be scripted and integrated into a built pipeline for generating automatic documentation.

The other benefit responsible for the growing use of Diagrams as code to create software architecture is that it enables the use of text-based tooling, which most software developers already use.

What is Diagram?

Diagram actually allows you to draw cloud system architecture without drawing them on any tools. You can simply write your architecture code and place them in SCM. It supports major providers such as AWS, Azure, GCP, Kubernetes, OpenStack, Oracle Cloud, etc. but supports drawing on-premise infrastructure as well.

Installing Diagram

The diagram is available as a python library for python version 3.6 and above. Install the diagram you can run below pip command:

$ pip3 install diagrams

To render the image created by diagrams you need to install a tool called Graphviz, which basically helps python code to render the diagram images. Run the below command to install graphviz as per your OS:

# for ubuntu
$ sudo apt install graphviz

How to use diagrams

You must import all the necessary modules of the diagrams into your python code. They are called nodes. Nodes represent the system components. To import you need to follow the below steps syntax.

from diagrams.aws.compute import ECS

In the above example, we are importing the ECS node from the compute resource of AWS.

Sample Example

The sample example for the diagram are as follows:

from diagrams import Cluster, Diagram
from diagrams.aws.compute import ECS
from diagrams.aws.database import ElastiCache, RDS
from diagrams.aws.network import ELB
from diagrams.aws.network import Route53

with Diagram("Clustered Web Services", show=False):
    dns = Route53("dns")
    lb = ELB("lb")

    with Cluster("Services"):
        svc_group = [ECS("web1"),
    with Cluster("DB Cluster"):
        db_master = RDS("userdb")
        db_master - [RDS("userdb ro")]

    memcached = ElastiCache("memcached")

    dns >> lb >> svc_group
    svc_group >> db_master
    svc_group >> memcached


Diagram represents a global diagram context.

with Diagram("Clustered Web Services", show=False):

show=False Will disable the automatic file opening when you generate the diagram.

Data Flow

Data Flow and how to connect nodes together:

>> nodes connection from the left to the right direction.

<< Connect nodes from right to left direction.

 Connect nodes in no direction. Undirected.

You can change the data flow direction with the direction parameter. Default is LR. (Left to Right)


Clusters allow you to group the nodes in an isolated group.

 with Cluster("Services"):
        svc_group = [ECS("web1"),

You can create a cluster context with the Cluster class. And you can also connect the nodes in a cluster to other nodes outside a cluster. There is no depth limit of nesting so that you can imagine the possibilities.

Generating the Diagram

To generate the diagram you can simple python command to run the code.

$ python3 diagram-test.py

The above command then will run the code snippet and generate the image.



The diagram is not the only option, you can use draw.io, Cloudgram, etc to have the functionality of saving the XML generated in Git. But diagram gives the power of Architecture as a code(AaC).

Written by 

Himanshu is a Software Consultant[[Devops]] at Knoldus Software LLP. He loves to explore and learn new tools and technologies.