Diagrams: Diagram as Code

When diagrams become too cluttered with connections, you can use the Node class to create invisible or blank placeholders. This allows you to point multiple edges to a single 'invisible' point within a Cluster, which then branches out to the actual target nodes, effectively simplifying the visual flow.

To create a blank placeholder, use Node with the following attributes:

• shape="plaintext"
• width="0"
• height="0"

from diagrams import Cluster, Diagram, Node

with Diagram("Less Edges Example", show=False) as diag:
    with Cluster(""):
        # Create a blank placeholder
        blankHA = Node("", shape="plaintext", width="0", height="0")

        with Cluster("Database HA"):
            db = PostgreSQL("users")
            # Connect the placeholder to the cluster content
            blankHA >> db

    # Connect ingress to the placeholder instead of every individual node
    ingress >> blankHA

You can implement the C4 model for software architecture visualization using the diagrams.c4 package. This package provides specific node classes (Person, Container, Database, System, SystemBoundary) and a Relationship class to define the hierarchy and interactions of a software system.

Key components include:

• Person: Represents users or actors.
• Container: Represents a deployable unit (e.g., a web app, mobile app, or API).
• Database: Represents data storage.
• System: Represents a software system (can be marked as external=True).
• SystemBoundary: Used to group related containers within a specific system context.
• Relationship: Used to define directed edges between nodes with descriptive text.

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

graph_attr = {
    "splines": "spline",
}

with Diagram("Container diagram for Internet Banking System", direction="TB", graph_attr=graph_attr):
    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 single page application.",
        )

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

        mobileapp = Container(
            name="Mobile App",
            technology="Xamarin",
            description="Provides a limited subset of the Internet banking functionality to customers via their mobile device.",
        )

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

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

    email = System(name="E-mail System", description="The internal Microsoft Exchange e-mail system.", external=True)

    mainframe = System(
        name="Mainframe Banking System",
        description="Stores all of the core banking information about customers, accounts, transactions, etc.",
        external=True,
    )

    customer >> Relationship("Visits bigbank.com/ib using [HTTPS]") >> webapp
    customer >> Relationship("Views account balances, and makes payments using") >> [spa, mobileapp]
    webapp >> Relationship("Delivers to the customer's web browser") >> spa
    spa >> Relationship("Make API calls to [JSON/HTTPS]") >> api
    mobileapp >> Relationship("Make API calls to [JSON/HTTPS]") >> api

    api >> Relationship("reads from and writes to") >> database
    api >> Relationship("Sends email using [SMTP]") >> email
    api >> Relationship("Makes API calls to [XML/HTTPS]") >> mainframe
    customer << Relationship("Sends e-mails to") << email

You can represent relationships and data flow between nodes using Python shift operators.

• >>: Connects nodes in a left-to-right direction.
• <<: Connects nodes in a right-to-left direction.
• -: Connects nodes with no direction (undirected).

Note on Operator Precedence: When mixing the undirected operator - with shift operators >> or <<, use parentheses to avoid unexpected results caused by Python's operator precedence.

Note on Rendering Order: The order of rendered diagrams is the reverse of the declaration order in your code.

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB
from diagrams.aws.storage import S3

with Diagram("Web Services", show=False):
    ELB("lb") >> EC2("web") >> RDS("userdb") >> S3("store")
    ELB("lb") >> EC2("web") >> RDS("userdb") << EC2("stat")
    (ELB("lb") >> EC2("web")) - EC2("web") >> RDS("userdb")

If you prefer using Docker for a consistent development environment, follow these steps from the diagrams root directory:

1. Build the image: Use the development Dockerfile to build the diagrams:1.0 image.
2. Run the container: Start a background container named diagrams and mount your current directory to /usr/src/diagrams inside the container.
3. Verify the setup: Run unit tests and the autogen.sh script inside the container to ensure everything is configured correctly.

Requirements: Docker must be installed on your system.

# 1. Build the docker image
docker build --tag diagrams:1.0 -f ./docker/dev/Dockerfile .

# 2. Create and run the container in the background with source code mounted
docker run -d \
-it \
--name diagrams \
--mount type=bind,source="$(pwd)",target=/usr/src/diagrams \
diagrams:1.0

# 3. Run unit tests inside the container
docker exec diagrams python -m unittest tests/*.py -v

# 4. Run the autogen script inside the container
docker exec diagrams ./autogen.sh