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.