DEV Community

Cover image for Diagrams as code
Joris Conijn for AWS Community Builders

Posted on • Originally published at


Diagrams as code

Most of you have heard of “infrastructure as code” by now. But building cloud infrastructures is more than coding infrastructure. In this blog I will show you how I make my own live easier by generating infrastructure diagrams from code.
When you have read my previous blogs about Commit messages done the right way. You are not surprised that I like to make things easy for the reader. When you are new to a team, or you are not familiar with a specific repository that your team maintains. It helps when the of the repository helps you understand what the repository does.

A picture is worth a thousand words!

Nice diagrams will help you a lot! But often they are either created in a program that you don’t master. Or you don’t have a access or a license to it. This makes it harder to keep the images up to date. And easier not to update them at all.
By managing the diagrams the same way as we manage our infrastructure. We also get the same benefits! Not only that when you make a change to your infrastructure you can update the image in the same commit. This makes it easier for the reviewer. Because, next to the code change he also will see a visual presentation of the change.

How does it work?

Enough about the theory, how do you do that? Within Python there is a package named diagrams. The website has a lot of examples I copied a few to this article.
First we will configure a poetry environment. Afterwards we will install the dependency.

mkdir diagrams-as-code
cd diagrams-as-code
poetry init
poetry add diagrams
Enter fullscreen mode Exit fullscreen mode

Once you have done that, we can create a file called

from diagrams import Diagram
from import EC2
from import RDS
from import ELB

with Diagram("Grouped Workers", show=False, direction="TB", filename="images/grouped_workers"):
    ELB("lb") >> [EC2("worker1"),
                  EC2("worker5")] >> RDS("events")
Enter fullscreen mode Exit fullscreen mode

As you can see the syntax is pretty straight forward. We have 5 workers that are behind a load balancer. The workers can connect to an RDS database named events. When you then run the following command:

poetry run python
Enter fullscreen mode Exit fullscreen mode

The output looks like this:

Grouped Workers

Pretty cool right?
Let’s do another one, we will create a file called

from diagrams import Cluster, Diagram
from import ECS
from import ElastiCache, RDS
from import ELB
from import Route53

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

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

    with Cluster("DB Cluster"):
        db_primary = RDS("userdb")
        db_primary - [RDS("userdb ro")]

    memcached = ElastiCache("memcached")

    dns >> lb >> svc_group
    svc_group >> db_primary
    svc_group >> memcached
Enter fullscreen mode Exit fullscreen mode

So this example is a bit more complex. We now introduced Route53, and we added a caching mechanism. To clarify the grouping we made use of the Cluster option. And when we run the following command:

poetry run python
Enter fullscreen mode Exit fullscreen mode

We will get the following output:

Clustered Web Services


You will receive the same benefits from “infrastructure as code”. When you manage your “diagrams as code”. Version control comes out of the box.
Because you combine the infrastructure code change. With the diagram code change you make the life of you and your teammates a lot easier.
Photo by Luca Bravo on Unsplash.

Top comments (2)

pbnj profile image
Peter Benjamin (they/them)

Cool. Didn't know about the diagrams python library.

Some notable mentions:

  • mermaid.js: supports various types of diagrams(e.g. gantt, flowchart, sequence, class, state, entity relationships, pie chart, git graphs, mindmaps, ...etc; native rendering supported on GitHub/GitLab (i.e. if you visit a markdown file with mermaid codeblock, GH/GL will render the diagram instead of showing the codeblock)
  • d2
aarone4 profile image
Aaron Reese

+1 for mermaid.js

An Animated Guide to Node.js Event Loop

Node.js doesn’t stop from running other operations because of Libuv, a C++ library responsible for the event loop and asynchronously handling tasks such as network requests, DNS resolution, file system operations, data encryption, etc.

What happens under the hood when Node.js works on tasks such as database queries? We will explore it by following this piece of code step by step.