sammcj/diagrams-as-code

Diagrams as Code

Generate architecture and infrastructure diagrams using the Python diagrams library. Diagrams are Python scripts that render to image files via Graphviz.

Workflow

1. Check prerequisites - verify graphviz and diagrams are installed
2. Write the diagram script to a .py file in the user's working directory
3. Run it with python3 <file>.py
4. Report the output path to the user (image appears in working directory)

Prerequisites check

command -v dot >/dev/null || brew install graphviz
uv pip install --system diagrams 2>/dev/null || pip install diagrams

Without graphviz, the script fails with a cryptic error. Always verify first.

Core API

Diagram context manager

from diagrams import Diagram

with Diagram(
    name="Title",           # used as default filename (slugified)
    filename="output",      # override filename (no extension)
    direction="LR",         # LR | RL | TB | BT
    curvestyle="spline",    # spline | ortho | curved | polyline
    outformat="png",        # png | jpg | svg | pdf | dot (or list)
    show=False,             # ALWAYS False - prevents auto-opening
    strict=False,           # merge duplicate edges
    autolabel=False,        # prefix labels with provider/type
    graph_attr={},          # graphviz graph attributes
    node_attr={},           # graphviz node attributes
    edge_attr={},           # graphviz edge attributes
):
    ...

Always set show=False so the script runs non-interactively.

Nodes

Import from diagrams.<provider>.<category>:

from diagrams.aws.compute import EC2, Lambda, ECS
from diagrams.aws.database import RDS, Aurora
from diagrams.aws.network import ELB, Route53, CloudFront
from diagrams.k8s.compute import Pod, Deployment
from diagrams.onprem.database import PostgreSQL, MySQL
from diagrams.onprem.network import Nginx

See references/providers.md for the full provider and category listing with common node names.

Data flow operators

ELB("lb") >> EC2("web") >> RDS("db")    # left to right
RDS("db") << EC2("web")                  # right to left
RDS("primary") - RDS("replica")           # undirected
ELB("lb") >> [EC2("w1"), EC2("w2")]      # fan-out to list

Operator precedence matters: - (subtraction) binds more tightly than >> / << (bitshift) in Python, so A >> B - C parses as A >> (B - C). Wrap in parentheses when mixing: (A >> B) - C.

Clusters

from diagrams import Cluster

with Cluster("VPC"):
    with Cluster("Private Subnet"):
        svc = [ECS("svc1"), ECS("svc2")]

Unlimited nesting depth. Clusters accept graph_attr for styling (e.g. background colour).

Edges

from diagrams import Edge

node_a >> Edge(label="HTTPS", color="darkgreen", style="dashed") >> node_b

Attributes: label (text on the edge), color (X11 name or hex), style (solid | dashed | dotted | bold).

Custom nodes

from diagrams.custom import Custom

svc = Custom("My Service", "./icon.png")  # local PNG, ideally 256x256

Key Techniques

• Direction: use TB for layered/hierarchical diagrams, LR for pipelines and flows
• Transparent background: graph_attr={"bgcolor": "transparent"}
• Multiple outputs: outformat=["png", "svg"]
• Reduce edge noise: import Node from diagrams and create blank junctions with Node("", shape="plaintext", width="0", height="0"), or merge overlapping edges with graph_attr={"concentrate": "true", "splines": "spline"}
• Assign nodes to variables when they connect to multiple other nodes
• PEP 723 for standalone scripts so uv run handles the dependency automatically:

  # /// script
  # dependencies = ["diagrams"]
  # ///