Creating Diagrams as Code

Creating diagrams programmatically offers significant advantages over manual drawing tools: version control, reproducibility, and consistency across documentation. This tutorial covers two approaches for creating diagrams as code.

Python Diagrams Package

The diagrams Python package allows you to draw cloud system architecture diagrams using Python code. It supports major cloud providers (AWS, Azure, GCP), on-premise infrastructure, and custom icons.

Installation

pip install diagrams

You also need Graphviz installed and available on your PATH.

AWS Architecture Example

Here’s how to create a clustered web services diagram:

from diagrams import Cluster, Diagram
from diagrams.aws.compute import ECS
from diagrams.aws.database import ElastiCache, RDS
from diagrams.aws.network import ELB, Route53

with Diagram("Clustered Web Services", show=False) as diag:
    dns = Route53("dns")
    lb = ELB("lb")

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

    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

C4 Model Diagrams

The diagrams package supports the C4 model for visualizing software architecture:

from diagrams import Diagram
from diagrams.c4 import Person, Container, Database, System, SystemBoundary, Relationship

with Diagram("Container diagram for Internet Banking System", direction="TB") as diag:
    customer = Person(
        name="Personal Banking Customer",
        description="A customer of the bank, with personal bank accounts."
    )

    with SystemBoundary("Internet Banking System"):
        webapp = Container(
            name="Web Application",
            technology="Java and Spring MVC",
            description="Delivers the static content and the Internet banking SPA.",
        )

        spa = Container(
            name="Single-Page Application",
            technology="Javascript and Angular",
            description="Provides Internet banking functionality via web browser.",
        )

        api = Container(
            name="API Application",
            technology="Java and Spring MVC",
            description="Provides Internet banking functionality via JSON/HTTPS API.",
        )

        database = Database(
            name="Database",
            technology="Oracle Database Schema",
            description="Stores user registration, credentials, access logs.",
        )

    email = System(name="E-mail System", external=True)
    mainframe = System(name="Mainframe Banking System", external=True)

    customer >> Relationship("Visits using [HTTPS]") >> webapp
    customer >> Relationship("Views and makes payments") >> spa
    webapp >> Relationship("Delivers to browser") >> spa
    spa >> Relationship("API calls [JSON/HTTPS]") >> api
    api >> Relationship("reads/writes") >> database
    api >> Relationship("Sends email [SMTP]") >> email
    api >> Relationship("API calls [XML/HTTPS]") >> mainframe

Custom Icons

You can use custom icons for components not included in the standard providers:

from diagrams import Diagram, Cluster
from diagrams.custom import Custom
from urllib.request import urlretrieve

with Diagram("Custom with remote icons", show=False, direction="LR") as diag:
    # Download icon image files
    diagrams_url = "https://github.com/mingrammer/diagrams/raw/master/assets/img/diagrams.png"
    diagrams_icon = "diagrams.png"
    urlretrieve(diagrams_url, diagrams_icon)

    diagrams = Custom("Diagrams", diagrams_icon)

    with Cluster("Some Providers"):
        openstack_url = "https://github.com/mingrammer/diagrams/raw/master/resources/openstack/openstack.png"
        openstack_icon = "openstack.png"
        urlretrieve(openstack_url, openstack_icon)

        openstack = Custom("OpenStack", openstack_icon)

        elastic_url = "https://github.com/mingrammer/diagrams/raw/master/resources/elastic/saas/elastic.png"
        elastic_icon = "elastic.png"
        urlretrieve(elastic_url, elastic_icon)

        elastic = Custom("Elastic", elastic_icon)

    diagrams >> openstack
    diagrams >> elastic

Mermaid Diagrams

For simpler diagrams that don’t require external dependencies, Mermaid provides a markdown-based syntax. Mermaid is supported natively in many documentation platforms including GitHub and Mintlify.

Neural Network Architecture Example

Here’s a Mermaid flowchart showing an upcycled MoE (Mixture of Experts) block:

Model Architecture Visualization

For visualizing trained model architectures (ONNX, TensorFlow, PyTorch, etc.), we recommend Netron - a viewer for neural network, deep learning, and machine learning models. Netron supports many formats including:

ONNX (.onnx)
TensorFlow Lite (.tflite)
TensorFlow (.pb, .meta, SavedModel)
Keras (.h5, .keras)
PyTorch (.pt, .pth)
Core ML (.mlmodel, .mlpackage)

You can use the web version or install it locally.

When to Use Each Tool

Tool	Best For
Python diagrams	Cloud architecture, infrastructure diagrams, C4 models
Mermaid	Quick flowcharts, sequence diagrams, embedded in markdown
Netron	Visualizing trained ML model architectures

Resources

Edit this page on GitHub or file an issue.

Categories

Tutorials

Creating Diagrams as Code

Python Diagrams Package

Installation

AWS Architecture Example

C4 Model Diagrams

Custom Icons

Mermaid Diagrams

Neural Network Architecture Example

Model Architecture Visualization

When to Use Each Tool

Resources

​Python Diagrams Package

​Installation

​AWS Architecture Example

​C4 Model Diagrams

​Custom Icons

​Mermaid Diagrams

​Neural Network Architecture Example

​Model Architecture Visualization

​When to Use Each Tool

​Resources

Python Diagrams Package

Installation

AWS Architecture Example

C4 Model Diagrams

Custom Icons

Mermaid Diagrams

Neural Network Architecture Example

Model Architecture Visualization

When to Use Each Tool

Resources