Diagrams As Code

We need better Charts
Mermaid Chart logo

Mermaid Chart

www.mermaidchart.com
Structurizr logo

Structurizr

structurizr.com

Visualise, document and explore your software architecture with Structurizr

Transform Your Business With AI logo

Transform Your Business With AI

lucid.co

Use powerful capabilities in Lucid to document the current state of your business. Keep people and AI agents aligned and moving into the future.

Security-first diagramming for teams | draw.io logo

Security-first diagramming for teams | draw.io

www.drawio.com

Free diagramming application with 100M+ users. Store your data wherever you want—we can't access it.
UML Diagrams
ℹ️ (2025-08-11T20:13.571Z)
Perplexity Query
(2025-08-11T20:13
.571Z)
Question:
Write a comprehensive one-page article about "Diagrams as Code".
Model: sonar-pro

Response from sonar-pro :

Diagrams as Code is the practice of defining a diagram’s content and structure in text-based source files and rendering it via tooling, rather than drawing it manually in a GUI editor. [tjpo2w] It matters because it brings the rigor of software development—version control, reviews, automation—to visual documentation, keeping diagrams accurate and easy to maintain alongside code. [tjpo2w] [anzw40]
Introduction
  • Diagrams as Code turns visual models into code, letting teams describe nodes, relationships, and layout through declarative or programmatic syntax that a renderer converts into images. [tjpo2w] By aligning with “docs as code,” it improves traceability, collaboration, and accessibility for technical documentation. [tjpo2w]
Main Content
  • The core idea is to write diagrams in human-readable text (e.g., Markdown -adjacent DSLs, YAML / JSON , or general-purpose languages like Python ) and use a tool to generate SVG/PNG on demand. [tjpo2w] This shifts effort from pixel-perfect editing to expressing intent—what components exist and how they connect—while the tool handles spacing, alignment, and styling. [anzw40] Because the source is text, changes are diffable and reviewable in pull requests, enabling the same CI/CD workflows used for code. [tjpo2w]
  • Practical examples span software architecture, cloud/network topologies, data flows, and onboarding docs. For instance, engineers can script cloud architectures—VPCs, load balancers, databases—and regenerate diagrams as infrastructure evolves, avoiding stale visuals. [934ur2] Teams often embed these generated images in READMEs so contributors see up-to-date architecture at a glance while the code lives in the repo for easy edits. [fkjo1n] Python-based libraries can define AWS/Azure/GCP components in a few lines and render architecture views programmatically. [jm27zz]
  • Benefits include speed for developers who think in code, consistency across diagrams, and focus on content rather than styling minutiae. [anzw40] Version history, change control, and automated rebuilds ensure diagrams stay aligned with reality, improving reliability of documentation in fast-moving DevOps environments. [tjpo2w] [934ur2] Accessibility improves as the text source can be read by assistive technologies or linked from the image for more inclusive documentation. [tjpo2w]
  • Considerations include learning curve for non-developers, limits of auto-layout for complex visuals, and the need to choose tools that fit governance and security requirements. Large, dense diagrams may require iterative refinement or layering into multiple views to remain readable, and teams should establish conventions (naming, icon sets, folder structure) to keep outputs coherent across repositories. [anzw40] [tjpo2w]
Current State and Trends
  • Adoption is growing among software, platform, and data teams that already practice “as code” workflows, particularly where architectures change frequently and manual diagrams fall out of date. [934ur2] [tjpo2w] Organizations report improved reviewability and maintainability when diagrams live with the codebase and participate in CI pipelines. [tjpo2w] [fkjo1n]
  • Key players and technologies include general approaches endorsed by digital government standards, plus toolchains that script diagrams using Python or DSLs for cloud and systems architecture. [tjpo2w] [jm27zz] Recent developments emphasize automating generation from live infrastructure descriptions so that visuals update as environments change, reducing drift between docs and production. [934ur2] [jm27zz]
Future Outlook
  • Diagrams as Code is likely to deepen integration with IaC and observability, auto-generating context-specific views from source-of-truth systems and embedding them in developer portals and runbooks. [934ur2] Expect richer interactivity, policy checks on diagram changes, and standardized taxonomies that make multi-cloud and hybrid architectures clearer and auditable at scale. [934ur2] [jm27zz]
Conclusion
  • Diagrams as Code brings code-like discipline to visuals, making architecture diagrams faster to create, easier to review, and less likely to rot. [tjpo2w] [anzw40] As automation and integrations advance, expect diagrams to become living assets that mirror systems in near real time. [934ur2]

Citations

Based on agent training and emerging infrastructure-as-code patterns, agents have strong fluency with several formats beyond the basics you mentioned. Here are the most promising ones: [5vm02s] [hsw9sd]

Infrastructure Configuration Languages

HCL (HashiCorp Configuration Language) is the declarative syntax powering Terraform and other HashiCorp tools. Agents readily read, understand, and write HCL because it balances human readability with machine parsability through its block-based structure, supports interpolation and functions, and is provider-agnostic. For users, it serves as a bridge between infrastructure intent and cloud provisioning—you describe what resources you want, and the tooling handles how to create them. [hsw9sd] [t8q5bh] [lycgb1]
CUE (Configure, Unify, Execute) takes configuration further by unifying data validation, templating, and policy enforcement in a single language. Agents trained on modern infrastructure tooling understand CUE's type-safe constraints and compositional approach. It helps users define complex system configurations with built-in validation, reducing the cognitive load of managing JSON Schema separately. CUE can import from and export to JSON, YAML, Protobuf, and OpenAPI. [0sbdno] [5ujobp]
Dhall is a programmable configuration language designed for security-conscious environments with guaranteed termination and no side effects. Its strong type system ensures configurations never fail at runtime if they type-check. For users, Dhall provides the power of computation in configs without the risks of arbitrary code execution. [3uggqx]

Visual-to-Text Formats

DOT ( Graphviz ) uses simple text syntax to describe nodes, edges, and graph layouts. Agents fluently generate DOT because it's pure declarative structure—you specify elements and relationships, and rendering engines handle visualization. Users can quickly communicate architectural diagrams, state machines, or dependency graphs through text that agents can both create and modify. [gq6t38] [tnpbn3]
PlantUML converts plain text descriptions into UML diagrams using an intuitive keyword-based syntax [ofo6uk] [j9mivu] . Agents understand the @startuml / @enduml blocks and relationship operators like --|> for inheritance [ofo6uk] . This lets users collaborate with agents on software architecture, sequence diagrams, and component relationships without touching a mouse [j9mivu] .
Excalidraw JSON stores whiteboard-style diagrams in a structured JSON schema with element arrays and application state. While more complex than PlantUML, agents can parse and generate .excalidraw files programmatically. Users get the benefit of hand-drawn aesthetic diagrams that are still machine-readable and version-controllable. [4qhw0v] [r0rtt7]

Why These Work

The pattern across all these formats is declarative structure with clear semantics . They describe desired end-states rather than procedural steps, making them easier for agents to reason about. They're text-based for version control, have formal grammars agents can parse reliably, and serve specific domains (infrastructure, diagrams, data validation) where the mapping from syntax to intent is unambiguous. [5vm02s] [hsw9sd]
Unlike SVG where agents must manipulate low-level rendering primitives, these formats operate at the conceptual level where both humans and agents naturally think—resources, relationships, constraints, and visual elements.

Sources

[nlo2ek]

Structured data and AI in 2026 - YouTube

[e9857y]

Mastering HashiCorp Configuration Language for Terraform

[7w3cid]

FOSDEM 2022 - A practical guide to CUE: patterns for everyday use

[83vxob]

Graphviz tutorial - YouTube

[anzw40] 2025, Apr 07. Understanding Diagrams as Code From Idea to Implementation - Gliffy . Published: 2024-02-16 | Updated: 2025-04-08

[jm27zz] 2025, Jun 15. Diagram-as-Code: Creating Dynamic and Interactive Documentation ... . Published: 2024-11-19 | Updated: 2025-06-16

[934ur2] 2025, Jun 15. Diagram as Code: Automate Diagrams for DevOps & Cloud - Draft1.ai . Published: 2024-12-03 | Updated: 2025-06-16

[tjpo2w] 2025, Jan 29. Diagrams as code - The GDS Way . Published: 2017-08-25 | Updated: 2025-01-30