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"]
  # ///

Diagrams Providers and Node Categories

All nodes are imported as from diagrams.<provider>.<category> import <Node>.

Cloud Providers

aws (Amazon Web Services)

Categories: analytics, ar, blockchain, business, compute, cost, database, devtools, enablement, enduser, engagement, game, general, integration, iot, management, media, migration, ml, mobile, network, nfv, quantum, robotics, satellite, security, storage

Common nodes:

• compute: EC2, Lambda, ECS, EKS, Fargate, Batch, ElasticBeanstalk
• database: RDS, Aurora, DynamoDB, ElastiCache, Redshift, Neptune
• network: ELB, ALB, NLB, Route53, CloudFront, VPC, APIGateway, DirectConnect
• storage: S3, EBS, EFS, FSx
• integration: SQS, SNS, StepFunctions, EventBridge, MQ
• security: IAM, Cognito, WAF, KMS, SecretsManager
• ml: Sagemaker, Rekognition, Comprehend, Bedrock

gcp (Google Cloud Platform)

Categories: analytics, api, compute, database, devtools, iot, ml, network, operations, security, storage

Common nodes:

• compute: AppEngine, GKE, Functions, Run, ComputeEngine
• database: BigTable, Datastore, Firestore, Memorystore, SQL
• analytics: BigQuery, Dataflow, PubSub, Dataproc
• network: LoadBalancing, CDN, DNS, VPC
• storage: GCS, Filestore

azure (Microsoft Azure)

Categories: analytics, compute, database, devops, general, identity, integration, iot, migration, ml, mobile, network, security, storage, web

Common nodes:

• compute: FunctionApps, VM, AKS, ContainerInstances, BatchAccounts
• database: CosmosDb, SQLDatabases, BlobStorage
• network: LoadBalancers, ApplicationGateway, Firewall, VirtualNetworks

alibabacloud

Categories: analytics, application, communication, compute, database, iot, network, security, storage, web

digitalocean

Categories: compute, database, network, storage

oci (Oracle Cloud Infrastructure)

Categories: compute, connectivity, database, devops, governance, monitoring, network, security, storage

ibm

Categories: analytics, applications, blockchain, compute, data, devops, general, infrastructure, management, network, security, social, storage, user

firebase

Categories: base, develop, extentions, grow, quality

outscale

Categories: compute, network, security, storage

openstack

Categories: apiproxies, applicationlifecycle, billing, compute, containerinfra, deployment, frontend, monitoring, multiregion, networking, nfv, objectstore, optimization, orchestration, packaging, sharedservices, storage, user, workloadprovisioning

Infrastructure / On-Premises

onprem

Categories: aggregator, analytics, auth, cd, certificates, ci, client, compute, container, database, dns, etl, gitops, groupware, iac, identity, inmemory, logging, messaging, mlops, monitoring, network, proxmox, queue, registry, search, security, storage, tracing, vcs, workflow

Common nodes:

• compute: Server, Nomad
• container: Docker, Containerd, LXC
• database: PostgreSQL, MySQL, MongoDB, Cassandra, CockroachDB, ClickHouse, Couchbase, MariaDB
• network: Nginx, HAProxy, Envoy, Istio, Traefik, Caddy, Apache, Consul
• ci: GithubActions, Jenkins, GitlabCI, CircleCI, TravisCI, Droneci
• queue: Kafka, RabbitMQ, Celery, ActiveMQ, Nats
• monitoring: Prometheus, Grafana, Datadog, Nagios, Zabbix, Splunk, Newrelic
• inmemory: Redis, Memcached
• logging: Fluentbit, Loki, Graylog
• vcs: Github, Gitlab, Gitea
• iac: Terraform, Ansible, Pulumi
• search: Elasticsearch, Solr
• security: Vault, Trivy, Falco
• cd: Spinnaker, Tekton
• tracing: Jaeger, Zipkin
• mlops: Mlflow

k8s (Kubernetes)

Categories: clusterconfig, compute, controlplane, ecosystem, group, infra, network, others, podconfig, rbac, storage

Common nodes:

• compute: Pod, Deployment, DaemonSet, StatefulSet, ReplicaSet, Job, CronJob
• network: Service, Ingress, NetworkPolicy
• storage: PV, PVC, StorageClass
• controlplane: APIServer, CCM, ControllerManager, KProxy, Kubelet, Scheduler
• rbac: ClusterRole, ClusterRoleBinding, Role, RoleBinding, ServiceAccount
• clusterconfig: HPA, LimitRange, Quota
• group: Namespace

Diagram Types

c4 (C4 Model)

Import from diagrams.c4:

• SystemBoundary, Container, Database, System, Person, SystemQueue, Relationship

generic

Categories: blank, compute, database, device, network, os, place, storage, virtualization

programming

Categories: flowchart, framework, language, runtime

saas (Software as a Service)

Categories: alerting, analytics, automation, cdn, chat, communication, crm, filesharing, identity, logging, media, payment, recommendation, security, social

Common nodes:

• chat: Slack, Teams, Discord, Telegram
• cdn: Cloudflare
• identity: Auth0, Okta
• logging: Datadog, Newrelic, Papertrail
• analytics: Snowflake, Stitch

custom

from diagrams.custom import Custom
node = Custom("Label", "/path/to/icon.png")

Node Documentation

Full node listings per provider: https://diagrams.mingrammer.com/docs/nodes/aws (replace aws with any provider name).