What the F**k is Diagram as Code

Introduction

In today’s fast-paced development environment, maintaining clear and up-to-date documentation is crucial. One innovative approach gaining popularity is “Diagram as Code” (DaC). This method allows developers to create and maintain diagrams using code, bringing numerous benefits in terms of automation, version control, and collaboration. In this blog post, we’ll explore what Diagram as Code is, its advantages, popular tools, and practical examples.

What is Diagram as Code?

Diagram as Code is a practice where diagrams are created and maintained through code rather than traditional graphical interfaces. By leveraging text-based languages and tools, developers can generate visual representations of systems, architectures, and workflows. These diagrams are often used in software development to visualize complex systems, making them easier to understand and communicate.

Benefits of Diagram as Code

1. Automation: Automate the creation and update of diagrams as your codebase evolves.
2. Version Control: Track changes in diagrams alongside your code using version control systems like Git.
3. Collaboration: Facilitate collaboration among team members by making diagrams accessible and editable in a code-friendly format.
4. Consistency: Ensure consistency in your diagrams, reducing the risk of outdated or incorrect documentation.
5. Integration: Easily integrate diagram generation into your CI/CD pipelines, ensuring up-to-date documentation with every deployment.

Popular Tools for Diagram as Code

1. PlantUML: A widely-used tool that allows you to create various types of diagrams using a simple and intuitive language.
2. Graphviz: Ideal for generating graphs and network diagrams from DOT files.
3. Mermaid: A JavaScript-based tool that supports integration with Markdown, making it perfect for static site generators and documentation platforms.
4. Diagrams: A Python library designed for creating cloud architecture diagrams, particularly useful for AWS, Azure, and GCP environments.

Practical Examples

Example 1: Creating a Sequence Diagram with PlantUML

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

This code generates a sequence diagram depicting a simple authentication flow between Alice and Bob.

Example 2: Visualizing Cloud Architecture with Diagrams

from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.network import ELB
from diagrams.aws.database import RDS

with Diagram("Web Service Architecture", show=False):
    with Cluster("VPC"):
        load_balancer = ELB("Load Balancer")
        web_servers = [EC2("Web Server 1"),
                       EC2("Web Server 2"),
                       EC2("Web Server 3")]
        database = RDS("Database")

    load_balancer >> web_servers >> database

This Python code generates a cloud architecture diagram illustrating a typical web service deployment on AWS.

Lastly, Diagram as Code offers a powerful approach to creating, maintaining, and sharing diagrams in a software development environment. By integrating diagrams directly into your codebase, you can automate updates, ensure consistency, and enhance collaboration among team members. Whether you’re using PlantUML, Graphviz, Mermaid, or Diagrams, adopting Diagram as Code can significantly improve your documentation workflow.

Cheers,

Sim