mingrammer-diagrams

name	mingrammer_diagrams
description	Generate cloud architecture diagrams (AWS, GCP, Azure, Kubernetes, on-prem) as code using the Python `diagrams` library (mingrammer/diagrams). Provides guidance on layout engines, graph attributes, cluster design, and edge routing for production-quality infrastructure diagrams, plus a runnable example gallery.
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep"]
user-invocable	true

Cloud Architecture Diagrams with mingrammer/diagrams

Generate production-quality architecture diagrams as code using the Python diagrams library with optimal Graphviz layout configuration. The same patterns render AWS, GCP, Azure, Kubernetes, and on-prem node sets — see resources/examples/ for runnable, multi-cloud examples.

Quick Start

# /// script
# requires-python = ">=3.9"
# dependencies = ["diagrams>=0.24"]
# ///
from diagrams import Cluster, Diagram, Edge
from diagrams.aws.compute import EC2, ECS, Lambda
from diagrams.aws.database import RDS, Elasticache
from diagrams.aws.network import ELB, CloudFront, Route53

with Diagram(
    "My Architecture",
    filename="my_arch",
    show=False,
    outformat="png",
    graph_attr={
        "rankdir": "LR",
        "splines": "ortho",
        "nodesep": "0.70",
        "ranksep": "0.90",
    },
):
    dns = Route53("DNS")
    cdn = CloudFront("CDN")

    with Cluster("Web Tier"):
        lb = ELB("ALB")
        web = [EC2("Web 1"), EC2("Web 2")]

    with Cluster("Data Tier"):
        db = RDS("Primary")
        cache = Elasticache("Redis")

    dns >> cdn >> lb >> web
    web[0] >> db
    web[1] >> cache
    db >> Edge(label="replication", style="dashed") >> RDS("Replica")

Run with: uv run diagram.py (requires Graphviz dot on PATH — see Dependencies).

Runnable Example Gallery

resources/examples/ holds self-contained, runnable diagram scripts — one .py source plus its committed .png render — covering all three major clouds:

Example	Provider	Shows
aws_web_service.py	AWS	3-tier web service, dot LR + ortho (the recommended default)
gcp_web_service.py	GCP	same shape on GKE / Cloud SQL / Memorystore
azure_web_service.py	Azure	same shape on AKS / SQL DB / Cache for Redis
aws_layout_spline.py	AWS	layout variant: splines=spline (soft curves)
aws_layout_vertical.py	AWS	layout variant: rankdir=TB (vertical flow)

Browse them with rendered previews in resources/examples/README.md (an autogenerated gallery). Reproduce any one:

uv run .claude/skills/mingrammer_diagrams/resources/examples/gcp_web_service.py

To re-render every PNG after editing an example, then refresh the gallery:

make -C .claude/skills/mingrammer_diagrams/scripts diagrams   # render *.png (needs Graphviz)
make -C .claude/skills/mingrammer_diagrams/scripts docs       # rebuild the gallery README

Recommended Layout Configurations

All three layout examples render the same 3-tier AWS architecture so the layout knobs are the only variable.

1. dot LR + ortho (Best for Architecture Diagrams)

Use this as the default. Clean, professional diagrams with left-to-right hierarchical flow and right-angle edge routing. See resources/examples/aws_web_service.png.

graph_attr = {"rankdir": "LR", "splines": "ortho", "nodesep": "0.70", "ranksep": "0.90"}

Why this works best:

• rankdir=LR matches how we read architecture flows (ingress -> compute -> data)
• splines=ortho gives clean right-angle edges that avoid visual clutter
• Default spacing balances density and readability; clusters stay visually distinct

2. dot LR + spline (Softer Alternative)

Same hierarchical layout with smoother curved edges — better when diagrams have many crossing connections. See resources/examples/aws_layout_spline.png.

graph_attr = {"rankdir": "LR", "splines": "spline", "nodesep": "0.70", "ranksep": "0.90"}

When to use: When ortho edges create too many bends or overlapping right-angle paths.

3. dot TB + ortho (Vertical Flow)

Top-to-bottom layout for request lifecycle or waterfall-style diagrams. See resources/examples/aws_layout_vertical.png.

graph_attr = {"rankdir": "TB", "splines": "ortho", "nodesep": "0.70", "ranksep": "0.75"}

When to use: Strong vertical flow (user request -> API gateway -> service -> database) or few parallel paths. Caution: TB grows very tall with many tiers — prefer LR for 3+ tiers.

Layout Engine Reference

The diagrams library uses Graphviz under the hood. The engine is set via:

with Diagram(...) as diag:
    diag.dot.engine = "dot"  # default

Engine Comparison (Evaluated on a 12-node 3-tier Architecture)

Engine	Best For	Cluster Support	Readability
dot	Hierarchical/layered (directed graphs)	Excellent	Excellent
neato	Spring-model graphs (undirected)	Poor	Fair
fdp	Force-directed (undirected)	Poor	Poor
sfdp	Large force-directed graphs	None	Poor
circo	Cyclic/circular structures	None	Fair
twopi	Radial/concentric layouts	None	Poor (overlaps)
osage	Grid-based cluster packing	Good	Fair

Verdict: Always use dot for architecture diagrams. The other engines are designed for undirected graphs and ignore the hierarchical, clustered structure that makes architecture diagrams readable.

dot Engine: Graph Attributes Reference

Direction (rankdir)

Value	Flow	Best For
LR	Left to Right	Architecture flows, data pipelines (recommended)
TB	Top to Bottom	Request lifecycles, waterfall flows
RL	Right to Left	Reverse flows (rare)
BT	Bottom to Top	Bottom-up compositions (rare)

Edge Routing (splines)

Value	Style	Best For
ortho	Right-angle segments	Clean, professional diagrams (recommended)
spline	Smooth curves	Edge-dense graphs with many crossings
curved	Curved arcs	Artistic/informal diagrams
polyline	Straight segments with bends	Moderate complexity
line	Direct straight lines	Simple graphs, few edges
false	No edges drawn	Node-only layouts

Spacing

Attribute	Default	Description
nodesep	0.70	Space between nodes within the same rank (inches)
ranksep	0.90	Space between ranks/layers (inches)

Spacing presets:

tight   = {"nodesep": "0.25", "ranksep": "0.3"}   # compact; edges may crowd
default = {"nodesep": "0.70", "ranksep": "0.90"}  # balanced readability
loose   = {"nodesep": "1.5",  "ranksep": "2.0"}   # breathing room for complex diagrams

Cluster Behavior

Attribute	Values	Description
compound	true/false	Allow edges between clusters (not just nodes)
newrank	true/false	Use single global ranking ignoring cluster boundaries
ordering	out/in	Constrain left-to-right ordering of edges at a node

Full Recommended Configuration

RECOMMENDED_GRAPH_ATTR = {
    "rankdir": "LR",
    "splines": "ortho",
    "nodesep": "0.70",
    "ranksep": "0.90",
    "fontsize": "12",
    "compound": "true",
}

Diagram Patterns

Multi-Tier Architecture

with Diagram("3-Tier App", filename="three_tier", show=False,
             graph_attr={"rankdir": "LR", "splines": "ortho"}):

    ingress = Route53("DNS") >> CloudFront("CDN")

    with Cluster("Web Tier"):
        lb = ELB("ALB")
        webs = [EC2(f"Web {i}") for i in range(1, 4)]

    with Cluster("App Tier"):
        apps = [ECS(f"App {i}") for i in range(1, 3)]
        worker = Lambda("Worker")

    with Cluster("Data Tier"):
        db = RDS("Primary")
        replica = RDS("Replica")
        cache = Elasticache("Redis")

    ingress >> lb >> webs
    webs[0] >> apps[0]
    webs[1] >> apps[1]
    webs[2] >> apps[0]
    apps[0] >> [db, cache]
    apps[1] >> [db, cache]
    worker >> db
    db >> Edge(label="replication", style="dashed") >> replica

Nested Clusters

with Cluster("VPC"):
    with Cluster("Public Subnet"):
        lb = ELB("ALB")
    with Cluster("Private Subnet"):
        app = ECS("App")
        db = RDS("DB")

Edge Styling

a >> Edge(label="HTTPS") >> b              # labeled
a >> Edge(style="dashed") >> b             # async / replication
a >> Edge(color="red", label="alert") >> b # colored
a >> Edge(label="sync", style="bold") << b # bidirectional

Common Pitfalls

1. Using the Wrong Engine

diag.dot.engine = "neato"  # WRONG — scatters nodes, ignores hierarchy
# CORRECT — dot respects rank ordering and clusters (default, no change needed)

2. Forgetting show=False

Diagram("Title")              # tries to open the image in your OS viewer — fails headless/CI
Diagram("Title", show=False)  # always disable for scripted generation

3. Node Labels with Newlines

Route53("Route53\nDNS")
ELB("Application\nLoad Balancer")

4. TB Layout Gets Too Tall

graph_attr = {"rankdir": "TB"}  # before: tall waterfall
graph_attr = {"rankdir": "LR"}  # after: wide pipeline

5. Overlapping Edges with ortho

graph_attr = {"splines": "spline"}                                     # A: switch to curves
graph_attr = {"splines": "ortho", "nodesep": "1.2", "ranksep": "1.5"}  # B: more separation

Output Formats

Diagram("Title", outformat="png")  # default, good for docs
Diagram("Title", outformat="svg")  # scalable, good for web
Diagram("Title", outformat="pdf")  # print-ready
Diagram("Title", outformat="dot")  # raw Graphviz source (for debugging)

Available Node Types

Detailed symbol references are in resources/. Read the relevant file when you need exact class names.

Resource File	Contents
resources/aws_nodes.md	All AWS symbols (322 classes) across 9 categories + alias cheat sheet.
resources/saas_nodes.md	SaaS providers: identity (Auth0, Okta), chat (Slack, Teams), +13 categories.
resources/flowchart_nodes.md	Standard flowchart shapes (24): Decision, Action, StartEnd, etc.
resources/programming_language_nodes.md	Language logos (23), framework logos (25), runtimes (1).
resources/custom_nodes.md	Custom(label, icon_path) — local images, remote URL download, icon-folder scanner.

Quick Reference (most common imports)

# AWS
from diagrams.aws.compute import EC2, ECS, EKS, Lambda, Fargate
from diagrams.aws.database import RDS, Aurora, Dynamodb, Elasticache
from diagrams.aws.network import ELB, ALB, NLB, CloudFront, Route53, VPC, APIGateway
from diagrams.aws.storage import SimpleStorageServiceS3 as S3, EFS
from diagrams.aws.integration import SQS, SNS, Eventbridge, StepFunctions

# GCP
from diagrams.gcp.compute import ComputeEngine, GKE, Run, Functions, AppEngine
from diagrams.gcp.database import SQL, Memorystore, Bigtable, Spanner, Firestore
from diagrams.gcp.network import LoadBalancing, CDN, DNS, VirtualPrivateCloud

# Azure
from diagrams.azure.compute import VM, AKS, FunctionApps, AppServices
from diagrams.azure.database import SQLDatabases, CacheForRedis, CosmosDb
from diagrams.azure.network import LoadBalancers, ApplicationGateway, CDNProfiles, DNSZones

# Flowcharts + custom icons
from diagrams.programming.flowchart import StartEnd, Action, Decision, InputOutput, Database
from diagrams.custom import Custom

Other Providers

from diagrams.k8s.compute import Pod, Deployment
from diagrams.onprem.database import PostgreSQL, MySQL, Redis
from diagrams.onprem.queue import Kafka, RabbitMQ
from diagrams.onprem.network import Nginx, HAProxy
from diagrams.programming.language import Python, Go, Rust

Dependencies

The diagrams library requires Graphviz:

brew install graphviz          # macOS
sudo apt-get install graphviz  # Ubuntu/Debian
dot -V                         # check installation

Python dependency (use PEP-723 inline metadata):

# /// script
# requires-python = ">=3.9"
# dependencies = ["diagrams>=0.24"]
# ///

File Structure

.claude/skills/mingrammer_diagrams/
├── SKILL.md                          # This file — agent operating manual
├── README.md                         # Human explainer (quickstart, architecture, troubleshooting)
├── CLAUDE.md                         # Maintainer decision log (ADRs)
├── scripts/
│   ├── _update_examples_readme.py    # Private helper: regenerates the examples gallery README
│   ├── test__update_examples_readme.py
│   ├── conftest.py                   # Coverage-reload fixture
│   └── Makefile                      # fix / ci / docs / diagrams
└── resources/
    ├── aws_nodes.md                  # AWS symbols + alias cheat sheet
    ├── saas_nodes.md                 # SaaS symbols
    ├── flowchart_nodes.md            # Flowchart shapes
    ├── programming_language_nodes.md # Language / framework logos
    ├── custom_nodes.md               # Custom icon patterns
    └── examples/                     # Runnable gallery (.py source + .png render)
        ├── README.md                 # Autogenerated gallery (do not hand-edit)
        ├── aws_web_service.py / .png
        ├── gcp_web_service.py / .png
        ├── azure_web_service.py / .png
        ├── aws_layout_spline.py / .png
        └── aws_layout_vertical.py / .png

For Maintainers

The development contract (make fix / make ci), file map, and design rationale (ADR log) live in CLAUDE.md. Consumer-facing docs are in README.md.