Diagram as Code (DaC)

Diagram as Code (DaC). It’s not often that a new paradigm shifts our perspective so profoundly, but DaC promises to do just that in the realm of infrastructure and architecture visualization.

🔶️ Genesis of Diagram as Code

Diagrams have been created manually using various graphical tools such as Microsoft Visio, draw.io, Lucid chart, smart draw, miro, etc.. . DaC turns this on its head by allowing us to generate and manipulate diagrams using code.

🔶️ Why Diagram as Code

DaC empowers us to treat diagrams like any other source code. We can version, track, and collaborate on diagrams with the same way we apply to our codebases. This aligns perfectly with the practices of Infrastructure as Code (IaC), enabling a seamless development experience.

🔶️ Core Benefits

Version Control: Just like application code, diagrams can be versioned, showcasing the evolution of an architecture over time.

Automation: With DaC, diagrams can be automatically updated as infrastructure changes, ensuring they always reflect the current state.

Collaboration: Teams can review, comment on, and improve diagrams through pull requests, enhancing team collaboration.

Consistency: DaC ensures that diagrams follow a consistent style, eliminating the discrepancies commonly found in manually created visuals.

🔶️ Integrating DaC into the Workflow

Incorporating DaC into our workflow means we can script architecture as part of the development process. As we write Terraform or AWS CloudFormation scripts to define infrastructure, we can simultaneously create diagrams that represent them.

🔶️ Challenges and Considerations

While DaC is promising, it’s not without challenges. The need for a certain level of technical skill to create diagrams and the initial setup time are considerations one must take into account.

🔶️ Tools of the Trade

Few tools have distinguished themselves as leaders. Developers are now scripting diagrams using syntax that is as straightforward as it is interpretable, thanks to resources like diagrams, PlantUML, Mermaid, and WebSequenceDiagrams.

I’m particularly excited to delve into two of these tools today.

🔶️ Diagrams (diagrams.mingrammer.com): This Python-based DaC tool is notable for its comprehensive documentation and a rich library of examples. It’s designed to turn the diagram creation process into a more developer-friendly experience.

Sample Code:

from diagrams import Cluster, Diagram, Edge
from diagrams.onprem.analytics import Spark
from diagrams.onprem.compute import Server
from diagrams.onprem.database import PostgreSQL
from diagrams.onprem.inmemory import Redis
from diagrams.onprem.aggregator import Fluentd
from diagrams.onprem.monitoring import Grafana, Prometheus
from diagrams.onprem.network import Nginx
from diagrams.onprem.queue import Kafka
with Diagram(name="Advanced Web Service with On-Premise (colored)", show=False):
    ingress = Nginx("ingress")
metrics = Prometheus("metric")
    metrics << Edge(color="firebrick", style="dashed") << Grafana("monitoring")
    with Cluster("Service Cluster"):
        grpcsvc = [
            Server("grpc1"),
            Server("grpc2"),
            Server("grpc3")]
    with Cluster("Sessions HA"):
        primary = Redis("session")
        primary \
            - Edge(color="brown", style="dashed") \
            - Redis("replica") \
            << Edge(label="collect") \
            << metrics
        grpcsvc >> Edge(color="brown") >> primary
    with Cluster("Database HA"):
        primary = PostgreSQL("users")
        primary \
            - Edge(color="brown", style="dotted") \
            - PostgreSQL("replica") \
            << Edge(label="collect") \
            << metrics
        grpcsvc >> Edge(color="black") >> primary
    aggregator = Fluentd("logging")
    aggregator \
        >> Edge(label="parse") \
        >> Kafka("stream") \
        >> Edge(color="black", style="bold") \
        >> Spark("analytics")
    ingress \
        >> Edge(color="darkgreen") \
        << grpcsvc \
        >> Edge(color="darkorange") \
        >> aggregator

Diagrams code Output

I encountered an error related to Python execution. Please Ensure that Graphviz is installed and its path is included in your system’s environment variables to enable image generation in your working directory once you execute your Python code.

🔶️ PlantUML (plantuml.com): Known for its simplicity and versatility, PlantUML allows the creation of various diagrams through an intuitive language. It’s supported by a Visual Studio Code extension with 1.7M downloads, signaling its ease of use. PlantUML supports numerous formats, including JSON and YAML data.

PlantUML

Sample Code

@startuml Sequence Diagram - Technical
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true
!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v16.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/Compute/all.puml
!include AWSPuml/ApplicationIntegration/APIGateway.puml
!include AWSPuml/General/Internetalt1.puml
!include AWSPuml/Database/DynamoDB.puml
actor User as user
APIGatewayParticipant(api, Credit Card System, All methods are POST)
LambdaParticipant(lambda,AuthorizeCard,)
DynamoDBParticipant(db, PaymentTransactions, sortkey=transaction_id+token)
Internetalt1Participant(processor, Authorizer, Returns status and token)
user -> api: Process transaction\nPOST /prod/process
api -> lambda: Invokes lambda with cardholder details
lambda -> processor: Submit via API token\ncard number, expiry, CVV
processor -> processor: Validate and create token
processor -> lambda: Returns status code and token
lambda -> db: PUT transaction id, token
lambda -> api: Returns\nstatus code, transaction id
api -> user: Returns status code
@enduml

PlantUML code Output

These tools are revolutionizing how we document and visualize complex architectures. Have you worked with any of these, or do you have others to recommend? Drop your suggestions in the comments below!

#diagrams #plantuml #diagramascode #architecturediagrams #prototyping #system architecture