Diagrams as Code

Type	Class
Resource	urn:ngm:class:diagrams-as-code
Domain	infrastructure
Status	stable
Maturity	established
Quality	0.52
Is a	Software Engineering Documentation As Code Declarative Specification Domain-Specific Language Text-Based Authoring Version-Controlled Artefact
Has part	Layout Engine Renderer Diagram Grammar Source File Build Pipeline Icon Library Theme Preview Plugin
Requires	Layout Algorithm Markdown Version Control Text Editor Render Toolchain
Enables	C4 Model Continuous Integration Pull Request Review Runbook Pull Request Review Living Documentation Architectural Decision Records Refactor-Time Consistency
Generated	by: process:vault-migrate/1.0 · at: 2026-09-22T12:41:39.024503178Z
Contrasts with	WYSIWYG Editor Microsoft Visio Lucidchart Drag-Drop Generative Image Models Whiteboard Photographs
Depends on	Sugiyama Algorithm Force-Directed Layout Eclipse Layout Kernel SVG Unicode Markdown
Implemented in layer	DocumentationLayer ToolingLayer BuildSystemLayer
Implements	Structurizr DSL Markdown Diagramming As Code Tool Mermaid PlantUML Graphviz DOT D2 TikZ Vega-Lite Wavedrom Pikchr Penrose
Legacy term id	IF-1078
Links	ADR ADR Antora Architectural Decision Records ASCIIflow Atlassian AWS Azure Bass Clements Kazman 2021 Software Architecture in Practice 4th Belouadi Lauscher Eger 2024 AutomaTikZ ICLR Brandes & Köpf 2001 Fast and Simple Horizontal Coordinate Assignment Brown 2018 C4 Model for Visualising Software Architecture Brown 2020 Software Architecture for Developers Volume 2 Build Pipeline BuildSystemLayer C4 Model C4 Model ChartGPT Class Diagram Confluence Continuous Integration D2 D2 Language Documentation Terrastruct Declarative Specification Deployment Diagram Diagram Grammar Diagrams.py Diagrams.py Documentation mingrammer Documentation as Code DocumentationDomain DocumentationLayer Docusaurus Domain-Specific Language Eclipse Layout Kernel Eclipse Layout Kernel Eclipse Layout Kernel ELK Documentation Kiel Entity-Relationship Diagram Excalidraw Flowchart Force-Directed Layout Fruchterman Reingold 1991 Graph Drawing by Force-Directed Placement Gansner Koutsofios North Vo 1993 A Technique for Drawing Directed Graphs Dot Gantt Chart GCP Generative Image Models Git GitHub GitLab Graphviz Graphviz Documentation AT&T Bell Labs Graphviz DOT Hugo Icon Library IEEE Infrastructure as Code Jekyll JSON Schema Kamada & Kawai 1989 Drawing General Undirected Graphs Kembhavi Salvato et al 2016 AI2D Diagram Is Worth a Dozen Images ECCV KnowledgeRepresentationDomain Kroki Kroki Unified Diagram API Yuzu Tech Kubernetes Larkin & Simon 1987 Why a Diagram Is Sometimes Worth Ten Thousand Words Layout Algorithm Layout Engine Lin Patel Rodriguez 2024 Benchmarking LLM Diagram Generation Living Documentation Lucidchart Lucidchart Drag-Drop MADR Markdown Any Decision Records Markdown Markdown Code Fence Mermaid Open-Source Project Mermaid v11 Documentation 2024 Microsoft Visio Mind Map Miro MkDocs Napkin AI Notion Nygard 2011 Documenting Architecture Decisions Object Management Group OMG OpenAPI Specification Oracle Cloud Infrastructure Penrose Pikchr PlantUML PlantUML Documentation Arnaud Roques Pre-commit Hooks Preview Plugin Pull Request Pull Request Review Refactor-Time Consistency Reingold Tilford 1981 Tidier Drawings of Trees Render Toolchain Renderer Rodriguez et al 2024 BigDocs-7.5M NeurIPS Runbook Runbook Satyanarayan Moritz Wongsuphasawat Heer 2017 Vega-Lite Grammar IEEE InfoVis Sequence Diagram SoftwareEngineeringDomain Source File Sphinx State Diagram Static Site Generator Structurizr DSL Structurizr DSL Documentation Simon Brown Sugiyama Algorithm Sugiyama Tagawa Toda 1981 Hierarchical System Structures IEEE TSMC SVG Text-Based Authoring Text Editor Theme ThoughtWorks Tech Radar ThoughtWorks Technology Radar Vol 30 April 2024 TikZ Timing Diagram ToolingLayer UML Unicode Vega Vega-Lite Version Control Version-Controlled Artefact W3C Walker 1990 Node-Positioning Algorithm for General Trees Wavedrom Web Components Whimsical Whiteboard Photographs Wilkinson 2005 The Grammar of Graphics WYSIWYG WYSIWYG Editor YAML Frontmatter Yang et al 2023 Set-of-Mark Prompting GPT-4V Ye et al 2020 Penrose ACM TOG SIGGRAPH AI Diagram Tools Anthropic Claude ChatGPT InfrastructureDomain Logseq Mermaid
Page resource	urn:visionflow:page:6ba687e3be527a90718a6ffad96649b33009359a9005e4a0b61fbb263fe76284
Related to	C4 Model Documentation As Code Excalidraw Notion AI Diagram Tools Logseq Kroki Diagrams.py ADR Static Site Generator
Standardized by	IEEE Mermaid Open-Source Project Object Management Group W3C Mermaid Open-Source Project OMG ThoughtWorks Tech Radar
Supports	Mind Map Sequence Diagram Class Diagram State Diagram Entity-Relationship Diagram Gantt Chart Flowchart Deployment Diagram Timing Diagram
Uses	JSON Schema OpenAPI Specification Markdown Code Fence YAML Frontmatter Web Components

Diagrams as Code (DaC) is a software-engineering discipline and tooling category in which technical diagrams (architecture, sequence, state, deployment, entity-relationship, Gantt, wireframe, timing, dataflow) are authored as plain-text source artefacts in a constrained, machine-readable grammar …

Semantic Classification

Content

Compositional Relationships (Components)

SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:DiagramGrammar))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:LayoutEngine))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:Renderer))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:SourceFile))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:BuildPipeline))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:IconLibrary))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:Theme))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:hasPart infrastructure:PreviewPlugin))

## Dependency Relationships
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:requires infrastructure:VersionControl))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:requires infrastructure:TextEditor))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:requires infrastructure:LayoutAlgorithm))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:requires infrastructure:RenderToolchain))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:dependsOn infrastructure:SugiyamaAlgorithm))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:dependsOn infrastructure:ForceDirectedLayout))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:dependsOn infrastructure:EclipseLayoutKernel))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:dependsOn infrastructure:SVG))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:dependsOn infrastructure:Markdown))

## Capability Relationships
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:enables infrastructure:PullRequestReview))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:enables infrastructure:ContinuousIntegration))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:enables infrastructure:LivingDocumentation))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:enables infrastructure:ArchitecturalDecisionRecords))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:enables infrastructure:C4Model))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:enables infrastructure:RefactorTimeConsistency))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:supports infrastructure:SequenceDiagram))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:supports infrastructure:ClassDiagram))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:supports infrastructure:StateDiagram))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:supports infrastructure:EntityRelationshipDiagram))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:supports infrastructure:GanttChart))

## Implementation Relationships
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:Mermaid))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:PlantUML))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:GraphvizDOT))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:D2))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:StructurizrDSL))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:TikZ))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:VegaLite))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:Wavedrom))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:Pikchr))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:implements infrastructure:Penrose))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:uses infrastructure:MarkdownCodeFence))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:uses infrastructure:JSONSchema))

## Reduction Relationships
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:reduces infrastructure:DiagramMaintenanceBurden))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:reduces infrastructure:DocumentationDrift))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:reduces infrastructure:OnboardingFriction))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:reduces infrastructure:ToolLockIn))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:reduces infrastructure:MergeConflictCost))

## Association Relationships
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:relatedTo infrastructure:DocumentationAsCode))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:relatedTo infrastructure:InfrastructureAsCode))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:relatedTo infrastructure:PolicyAsCode))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:relatedTo infrastructure:AIDiagramTools))
SubClassOf(infrastructure:DiagramsAsCode
  ObjectSomeValuesFrom(infrastructure:relatedTo infrastructure:Kroki))

## Data Properties (Characteristics)
DataPropertyAssertion(infrastructure:hasIdentifier infrastructure:DiagramsAsCode "IF-1078"^^xsd:string)
DataPropertyAssertion(infrastructure:authorityScore infrastructure:DiagramsAsCode "0.87"^^xsd:decimal)
DataPropertyAssertion(infrastructure:mermaidGitHubStars infrastructure:DiagramsAsCode "70000"^^xsd:integer)
DataPropertyAssertion(infrastructure:mermaidWeeklyDownloads infrastructure:DiagramsAsCode "12500000"^^xsd:integer)
DataPropertyAssertion(infrastructure:structurizrTeams infrastructure:DiagramsAsCode "50000"^^xsd:integer)
DataPropertyAssertion(infrastructure:thoughtworksRing infrastructure:DiagramsAsCode "Adopt"^^xsd:string)

## Property Constraints
SubClassOf(infrastructure:DiagramsAsCode
  DataAllValuesFrom(infrastructure:isTextSource xsd:boolean))
SubClassOf(infrastructure:DiagramsAsCode
  DataSomeValuesFrom(infrastructure:grammarFamily xsd:string))
SubClassOf(infrastructure:DiagramsAsCode
  DataMinCardinality(1 infrastructure:hasLayoutEngine xsd:string))
SubClassOf(infrastructure:DiagramsAsCode
  DataMinCardinality(1 infrastructure:rendersTo xsd:string))

## Annotations
AnnotationAssertion(rdfs:label infrastructure:DiagramsAsCode "Diagrams as Code"@en)
AnnotationAssertion(rdfs:comment infrastructure:DiagramsAsCode "Software-engineering discipline authoring technical diagrams as plain-text source in machine-readable grammars (Mermaid, PlantUML, Graphviz DOT, D2, Structurizr DSL, TikZ, Vega-Lite, Wavedrom, Pikchr, Penrose, Diagrams.py, Excalidraw scenes) stored in version control alongside application code, rendered to SVG/PNG/PDF at build time or in the browser; on ThoughtWorks Tech Radar Adopt ring (Vol 30 April 2024); default modality for ADRs, C4-model architecture documentation, runbooks; AI-augmented from 2023-2026 by Mermaid AI Chat, Eraser DiagramGPT, Excalidraw AI, Whimsical AI, Lucidchart AI, Miro AI, Napkin AI, Claude artifacts native Mermaid, ChatGPT canvas, Atlassian Rovo; contrasted with WYSIWYG vector tools (Visio, OmniGraffle, Lucidchart drag-drop, draw.io) lacking mergeable diffs and with generative image models lacking semantic structure."@en)
AnnotationAssertion(dcterms:identifier infrastructure:DiagramsAsCode "IF-1078"^^xsd:string)
AnnotationAssertion(dcterms:subject infrastructure:DiagramsAsCode "Documentation as Code, Software Architecture, C4 Model, Mermaid, PlantUML, Diagram Grammar, Layout Algorithms"@en)

)

Property Characteristics

AsymmetricObjectProperty(infrastructure:implements) AsymmetricObjectProperty(infrastructure:requires) AsymmetricObjectProperty(infrastructure:enables) AsymmetricObjectProperty(infrastructure:reduces) TransitiveObjectProperty(infrastructure:dependsOn) FunctionalDataProperty(infrastructure:hasIdentifier) FunctionalDataProperty(infrastructure:thoughtworksRing)


- ## About Diagrams as Code
- **Diagrams as Code** is the application of the "X as Code" pattern — pioneered by Infrastructure as Code (Terraform, Ansible, CloudFormation, Pulumi), Policy as Code (Open Policy Agent, Sentinel, Cedar) and Documentation as Code (MkDocs, Docusaurus, Antora, Sphinx) — to the domain of technical diagrams. The core proposition is that an architecture diagram, sequence diagram, state machine, deployment topology, or Gantt chart should be expressible as a small text file in a constrained grammar, committed to the same Git repository as the system it describes, reviewed in the same pull request that changes the system, rendered by the same build pipeline that produces the rest of the documentation, and rolled back via the same release machinery. Plain-text artefacts gain the full benefit of forty years of source-control tooling — diffs, blame, bisect, signed commits, branch protection, mergeability — which a binary `.vsd`, `.gliffy` or proprietary cloud diagram simply cannot match.
- The genre traces back to **Graphviz DOT** (Stephen North and Eleftherios Koutsofios, AT&T Bell Labs 1991), the first widely-adopted text-based diagram language. DOT's `digraph { A -> B -> C }` syntax remains the lingua franca of automated graph rendering, sustained by the Graphviz toolkit's `dot`, `neato`, `fdp`, `circo`, and `twopi` engines covering hierarchical, force-directed, and radial layouts. **TikZ** (Till Tantau 1995) brought programmable diagrams into the LaTeX ecosystem, becoming the de-facto standard for typographically precise figures in academic papers. **PlantUML** (Arnaud Roques 2009) extended the model to UML and beyond, leveraging Graphviz internally to render class, sequence, use-case, activity, state, component, and deployment diagrams from a compact Java-rendered grammar. The 2014 release of **Mermaid** (Knut Sveidqvist at Qlik Sweden) marked an inflection point: by targeting JavaScript rendering in the browser and aligning the grammar with Markdown code fences, Mermaid eliminated the server-side toolchain dependency that had limited the prior generation. GitHub's February 2022 enablement of native Mermaid rendering in Markdown — issues, pull requests, READMEs, gists, GitHub Pages — turned the language into a de-facto industry standard almost overnight. By January 2026, Mermaid claims 70,000+ GitHub stars and approximately 12.5 million weekly npm downloads.
- The discipline gained additional momentum from the **C4 Model** (Simon Brown 2018), which prescribes four nested abstraction levels — **System Context**, **Container** (deployable units), **Component** (internal modules), **Code** (class/sequence detail) — and is most naturally expressed in **Structurizr DSL**, a workspace-oriented grammar where a single source file defines elements once and the renderer produces multiple views (one per C4 level, plus deployment, dynamic, and filtered variants). Roughly 50,000 self-reported teams use the C4 model in production. **D2** (Alexander Wang at Terrastruct 2022) brought modern syntax design — first-class containers, clean comment forms, sensible defaults — and importantly offered four interchangeable layout engines (dagre, ELK, the proprietary TALA tuned for software architecture, and a fast native engine), addressing the long-standing complaint that DOT's `dot` engine produced unsightly results on dense graphs. **Diagrams.py** (mingrammer 2018) took a different tack: instead of a new DSL, it offered a Python API with curated provider icon sets (AWS, Azure, GCP, Kubernetes, OCI, Alibaba, IBM, DigitalOcean) so cloud architecture diagrams could be authored as ordinary Python scripts, executed to produce SVG/PNG.
- **Excalidraw** (Christopher Chedeau 2020) deserves special mention as a hybrid case: its hand-drawn sketchy aesthetic is the result of a graphical editor, but the scene is exported as JSON and is treated by many teams as the source-of-truth artefact alongside the SVG render. **Penrose** (Katherine Ye and collaborators at Carnegie Mellon 2020, ICFP/OOPSLA) represents the academic state-of-the-art: it separates mathematical content from visual style via a three-language model (Domain defines vocabulary, Substance instantiates objects, Style maps to graphics), enabling the same Substance file to produce dramatically different visualisations by swapping the Style. **Wavedrom**, **Vega-Lite** (Jeffrey Heer at the University of Washington Interactive Data Lab 2017), **Pikchr** (D. Richard Hipp of SQLite 2020), **Nomnoml**, and **ASCIIflow** fill remaining niches in digital timing diagrams, statistical visualisation, embedded PIC-style figures, and lo-fi ASCII inline diagrams respectively.
- ### The Engineering Case
- Why does the engineering community keep gravitating toward text-based diagrams? Five reinforcing arguments dominate the literature and practitioner blogs.
- **Mergeable diffs**: Two engineers editing different branches of an architecture diagram can merge their changes via standard Git three-way merge. WYSIWYG XML formats (`.drawio`, `.vsd`, `.gliffy`) theoretically permit textual diff but in practice every cosmetic move re-serialises coordinates and produces conflict markers in nearly every line. ThoughtWorks Tech Radar (Vol 30 April 2024) explicitly cites mergeability as the decisive criterion for placing diagrams-as-code in the Adopt ring.
- **Refactor-time consistency**: When a service is renamed, an API endpoint changes shape, or a database is split, an engineer can grep across the documentation tree and update diagrams alongside code in a single PR. With WYSIWYG diagrams, this kind of refactor either silently drifts or is deferred indefinitely, producing the well-known "stale architecture diagram pinned to the wall" failure mode.
- **Scripted generation**: Many high-value diagrams should be generated from a source-of-truth other than human authorship. Cloud topology can be generated from Terraform state (`terraform graph`, `inframap`, `cloudgraph`); database schemas from migrations (`dbml`, `schemaspy`, `dbdocs`); microservice dependency graphs from service-mesh telemetry (Istio's Kiali, Linkerd's tap); call graphs from runtime tracing (Datadog APM exports). Diagrams-as-code provides the human-readable rendering layer for these generated artefacts.
- **Build pipeline integration**: A static site generator (MkDocs, Docusaurus, Antora, Sphinx, Hugo, Jekyll) running in CI can lint, render, and publish diagrams as part of the regular documentation build. Broken diagram syntax fails the build the same way broken code fails CI, surfacing problems at the right moment rather than at reader-encounters-broken-diagram time.
- **Tool-lock-in avoidance**: When Visio license costs spike, when Lucidchart pricing changes, when a SaaS vendor disappears, an organisation with `.mmd` or `.dot` or `.puml` files in version control simply re-renders with any compatible tool. Binary cloud-locked diagrams are hostage to vendor pricing and availability.
- The trade-offs are real and worth naming: grammars must be learned (Mermaid is forgiving, Graphviz DOT and TikZ less so); auto-layout occasionally produces undesirable placements requiring hints (rank constraints, explicit positions, alternate engines); some diagram types (rich infographics, marketing material, presentation-quality keynote slides) remain better served by graphical tools; and onboarding a non-engineer collaborator into a DSL is harder than handing them a drag-drop editor.
- ### Core Mathematical and Algorithmic Foundations
- Layout — turning a graph specification into pixel coordinates — is the hard problem at the centre of diagrams-as-code. Decades of graph drawing research underpin the engines used by every major DaC grammar.
- #### Hierarchical (Layered) Layout — Sugiyama 1981
- The **Sugiyama-Tagawa-Toda algorithm** (IEEE Transactions on Systems, Man and Cybernetics, 1981, DOI 10.1109/TSMC.1981.4308636) decomposes the problem of drawing directed graphs into four sequential phases:
- **Cycle breaking**: Reverse a minimal set of edges to produce a directed acyclic graph (DAG). NP-hard exact; greedy heuristics achieve near-optimal results in O(|V| + |E|) time.
- **Layer assignment**: Partition vertices into horizontal (or vertical) layers respecting edge direction. Common choices include longest-path layering (O(|V| + |E|), produces wide graphs), Coffman-Graham (bounded width), and ILP-based optimal (Gansner et al. 1993, network-simplex relaxation, dominates `dot`).
- **Crossing minimisation**: Permute vertices within each layer to minimise edge crossings. NP-hard exact; barycentre and median heuristics with iterated sweep achieve good results in practice (Eades & Wormald 1994).
- **Coordinate assignment**: Compute final x-coordinates respecting permutations from phase 3 whilst minimising bend penalties and edge slope. Brandes-Köpf 2001 algorithm dominates modern implementations.
- This four-phase decomposition is the algorithmic basis of Graphviz `dot`, Mermaid flowchart engine, the dagre layout used by D2 and yFiles community editions, and the layered layout in Eclipse Layout Kernel (ELK).
- #### Force-Directed Layout — Fruchterman-Reingold 1991
- The **Fruchterman-Reingold algorithm** (Software: Practice and Experience 21(11), DOI 10.1002/spe.4380211102) models a graph as a physical system: vertices repel each other (Coulomb-like), edges attract their endpoints (Hooke-like), and iterative simulation converges to a minimum-energy configuration. Used for undirected graphs without natural hierarchy; produces aesthetically pleasing layouts for small-to-medium graphs (50-500 vertices) but scales poorly beyond. Variants include Kamada-Kawai 1989 (spring-embedder energy minimisation), Davidson-Harel 1996 (simulated annealing), and modern multilevel approaches (sfdp, FM³, ForceAtlas2 used by Gephi). Graphviz `neato`, `fdp` and `sfdp` implement this family.
- #### Tree Layout — Reingold-Tilford 1981
- Trees admit elegant linear-time layout via the **Reingold-Tilford tidy tree algorithm** (IEEE TSE 1981, "Tidier Drawings of Trees"). Used for Mermaid mindmaps, tree diagrams in Markmap, hierarchical org charts, syntactic parse trees. Walker 1990 extended to multi-child trees; Buchheim et al. 2002 produced the canonical O(n) implementation.
- #### Modern Layout Frameworks — ELK and beyond
- The **Eclipse Layout Kernel** (Christoph Schulze et al., Christian-Albrechts-Universität zu Kiel, ongoing since 2014) is a Java/JavaScript graph layout toolkit consolidating the above algorithms behind a unified configuration model. ELK powers D2, Eclipse Sirius, and several enterprise diagramming products. Terrastruct's proprietary **TALA** engine (used by D2 and Terrastruct's commercial product) is specifically tuned for software-architecture diagrams: it preserves logical groupings, avoids long edge runs, and produces compact layouts that consistently outperform `dot` on real-world architecture inputs in published benchmarks.
- ### Diagram Type Coverage
- A non-exhaustive enumeration of diagram types served by major DaC grammars, with the dominant tool for each:
- **Flowchart**: Mermaid `flowchart TD`, Graphviz `digraph`, D2 implicit
- **Sequence diagram**: Mermaid `sequenceDiagram`, PlantUML `@startuml`, WebSequenceDiagrams
- **Class diagram**: PlantUML, Mermaid `classDiagram`, D2
- **State diagram**: Mermaid `stateDiagram-v2`, PlantUML, SCXML
- **Entity-relationship**: Mermaid `erDiagram`, PlantUML, DBML, dbdocs
- **Gantt chart**: Mermaid `gantt`, PlantUML, vega-lite
- **C4 architecture**: Structurizr DSL, C4-PlantUML, Mermaid C4 (experimental)
- **Deployment/infrastructure**: Diagrams.py, D2, Structurizr deployment views, Cloudcraft
- **Mind map**: Markmap, Mermaid `mindmap`, PlantUML `@startmindmap`
- **Network diagram**: NwDiag, Graphviz, D2, Diagrams.py
- **Digital timing**: Wavedrom (canonical for hardware specs, IEEE/IETF drafts)
- **Statistical chart**: Vega-Lite, Vega, vega-lite-api
- **UML 2.5 (all 14 types)**: PlantUML (most complete), Mermaid (partial)
- **BPMN business process**: bpmn-js, Camunda Modeler, PlantUML BPMN extension
- **Petri net / state machine**: PlantUML, SCXML, statechart.js
- **Block diagram**: BlockDiag, Mermaid `block`, D2
- **Bytefield (packet layout)**: bytefield-svg, Wavedrom register variant
- **Kanban board**: Mermaid `kanban` (v11.4 December 2024), PlantUML
- **Architecture diagram (Mermaid v11)**: native `architecture-beta` block (October 2024)
- **Packet diagram (Mermaid v11)**: `packet-beta` for binary protocol layouts
- **ASCII art**: ASCIIflow, monodraw, draw.io ASCII export
- **Hand-drawn / sketchy**: Excalidraw, tldraw, rough.js stylings
- **Mathematical / category-theoretic**: TikZ-cd, Penrose, MetaPost
- ### Grammar Comparison
- A side-by-side overview of the dominant text grammars, organised by language style, layout family, and primary use case:
- **Mermaid**: JavaScript renderer, browser-side; declarative line-oriented syntax; nine first-class diagram types (flowchart, sequence, class, state, ER, Gantt, mindmap, kanban v11.4, architecture-beta v11); native GitHub/GitLab/Notion/Logseq/Claude rendering; weakness: complex layouts harder than D2.
- **PlantUML**: Java renderer, server-side; rich UML 2.5 coverage; older skin/styling system being modernised; weakness: requires Java runtime; strength: most complete UML coverage of any open-source grammar.
- **Graphviz DOT**: C engine via `dot`/`neato`/`fdp`/`circo`/`twopi`; declarative graph specification; weakness: aesthetic defaults; strength: dense graph rendering, ubiquity, scriptability.
- **D2**: Go renderer; modern syntax; four interchangeable layout engines (dagre, ELK, TALA proprietary, native); strength: software-architecture aesthetics, sensible defaults; weakness: smaller ecosystem than Mermaid.
- **Structurizr DSL**: workspace-oriented; single source produces multiple C4 views; strength: model coherence, C4 alignment; weakness: tied to C4 conceptual model.
- **Diagrams.py**: imperative Python; curated cloud-provider icon sets; strength: cloud architecture out-of-the-box; weakness: Python execution rather than declarative spec.
- **TikZ**: LaTeX programmable graphics; strength: typographic precision, academic-publication quality; weakness: steep learning curve, requires LaTeX toolchain.
- **Excalidraw scenes**: JSON scene format; strength: hand-drawn aesthetic, multiplayer collaboration; weakness: JSON not designed for hand-authoring (graphical editor in practice).
- **Penrose**: triple Domain/Substance/Style; strength: rigour and style separation; weakness: research-grade tooling, small ecosystem.
- **Vega/Vega-Lite**: JSON grammar of graphics; strength: statistical visualisation, charts; weakness: not designed for software architecture.
- **Wavedrom**: JSON timing/waveform; strength: digital timing diagrams in hardware/protocol specs; weakness: niche.
- **Pikchr**: PIC-derivative; strength: lightweight inline diagrams in Markdown; weakness: small ecosystem.
- **Nomnoml**: UML-lite browser-side; strength: simple class diagrams; weakness: feature set bounded.
- **BlockDiag / SeqDiag / ActDiag / NwDiag**: Python tooling; strength: comprehensive blockdiag family; weakness: slower development cadence than Mermaid/D2.
- **bpmn-js / Camunda Modeler**: BPMN 2.0 process diagrams; strength: BPMN standard compliance; weakness: BPMN itself is complex.
- **Markmap**: Markdown-to-mindmap; strength: mind-map from Markdown headings; weakness: niche to mindmap use.

- ### Worked Examples
- #### Mermaid sequence diagram
- A typical request-response flow rendered in five lines of Mermaid:

sequenceDiagram Client→>API Gateway: POST /orders API Gateway→>Order Service: gRPC PlaceOrder Order Service→>Postgres: INSERT Postgres⇒>Order Service: row_id Order Service⇒>API Gateway: OrderID API Gateway⇒>Client: 201 Created

- #### Mermaid C4 container view
- A C4-style container diagram in Mermaid's C4 dialect (still experimental in v11; C4-PlantUML is more mature):

C4Container Person(user, “Customer”, “Places orders”) System_Boundary(c1, “E-commerce”) { Container(web, “Web App”, “Next.js”) Container(api, “API”, “Go”) ContainerDb(db, “DB”, “Postgres”) } Rel(user, web, “uses”, “HTTPS”) Rel(web, api, “calls”, “gRPC”) Rel(api, db, “reads/writes”, “SQL”)

- #### Structurizr DSL workspace
- A minimal Structurizr DSL workspace generating system-context plus container views from a single model:

workspace { model { user = person “Customer” store = softwareSystem “E-commerce” { web = container “Web App” “Next.js” api = container “API” “Go” db = container “Database” “Postgres” } user → web “uses” web → api “calls” api → db “reads/writes” } views { systemContext store { include * autoLayout } container store { include * autoLayout } } }

- #### D2 software architecture
- D2's modern syntax with first-class containers and clean style:

direction: right user → web: HTTPS web → api: gRPC api → db: SQL ecommerce: { web: { shape: rectangle } api: { shape: rectangle } db: { shape: cylinder } }

- #### Diagrams.py cloud topology
- Diagrams.py renders cloud architecture as ordinary Python:

from diagrams import Diagram from diagrams.aws.compute import ECS from diagrams.aws.database import RDS from diagrams.aws.network import ELB with Diagram(“Web”, show=False): ELB(“lb”) >> ECS(“api”) >> RDS(“db”)

These are the diagram-genres engineers reach for daily; they illustrate the discipline’s core proposition — small, mergeable, regenerable text files are sufficient for the overwhelming majority of engineering diagramming needs.

The Kroki Unified API

The fragmentation of the DaC ecosystem produced demand for a unifying endpoint. Kroki (Yuzu Tech, open-source MIT-licensed) provides a single HTTP POST API that accepts source for any of ~30 grammars and returns SVG, PNG, PDF, JPEG, or Base64-encoded image. Supported engines include BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag, BPMN, Bytefield, C4-with-PlantUML, D2, DBML, Ditaa, Erd, Excalidraw, Graphviz, Mermaid, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, Symbolator, TikZ, UMLet, Vega, Vega-Lite, WaveDrom, and WireViz. Kroki can be self-hosted via docker compose up (image yuzutech/kroki and per-engine sidecars kroki-mermaid, kroki-blockdiag, kroki-bpmn) or used via the public instance at https://kroki.io. The Antora documentation pipeline (Asciidoctor + Asciidoctor Kroki) and the MkDocs mkdocs-kroki-plugin integrate Kroki into static-site builds. For teams whose internal documentation includes a heterogeneous mix of Mermaid, PlantUML, Graphviz and a long tail of niche grammars, Kroki eliminates the need to maintain N separate render toolchains.

AI-Assisted Authorship (2023-2026)

The advent of capable LLMs reshaped the DaC tooling landscape from 2023 onward. Several products and product features now bridge natural-language input and DaC output:
- Mermaid Chart AI (Q4 2023): The commercial fork of Mermaid by Knut Sveidqvist’s company added a GPT-4-powered chat interface for natural-language diagram generation, edit, and explanation. Pricing $10/user/month Pro.
- Eraser DiagramGPT (May 2023): Standalone product by Shin Kim, $4 MS er i es A C a ff e ina t e d C a p i t a l A p r i l 2023,$ 12M Series B Index Ventures November 2025. Generates AWS/cloud architecture diagrams from natural language and from textual cloud-config descriptions. $20/ m o n t hin d i v i d u a l,$ 40/month team.
- Excalidraw AI (November 2023): Lipis et al. at Excalidraw Plus released a GPT-4-backed feature that produces Mermaid source from a natural-language prompt and converts to Excalidraw scene JSON for sketchy-aesthetic rendering. $6/user/month.
- Whimsical AI (March 2023): Integrated mind-map and flowchart generation. Whimsical was founded 2017 by Kaspars Dancis and Steve Schoger; 5M+ registered users; $12/ u ser / m o n t h P ro;$ 30M Series A Insight Partners 2021.
- Lucidchart AI (February 2024 GA): Rolled out across 70M+ Lucid suite users; enterprise pricing from $20/user/month.
- Miro AI (July 2023 GA): 60M+ users; all paid tiers from $10/user/month; includes mind-map, flowchart and sticky-note clustering.
- Napkin AI (March 2024 private beta, GA Q3 2024): Founded by Pramod Sharma (ex-Osmo) and Jerome Scholler; $10 M A cce l see d O c t o b er 2024;$ 25M Lightspeed Series A March 2025. Generates visual summaries (data visualisations, decorative diagrams) from natural-language input or paragraph text.
- Anthropic Claude artifacts (June 2024): Native Mermaid rendering inside Claude’s artifact sandbox produced an inflection in casual diagramming; many users report Claude as their primary diagram-generation tool by 2025-2026.
- ChatGPT canvas (October 2024): Mermaid source editing inside a side-by-side canvas; native rendering inside ChatGPT itself was not yet shipped as of January 2026 (rendered only via copy-paste to a Mermaid-aware viewer).
- Atlassian Rovo (June 2024 GA, 100K+ activated paid users by September 2025): Embedded AI assistant across Jira and Confluence; generates Mermaid diagrams and explains existing ones.
- tldraw “Make Real” (November 2023): Steve Ruiz’s tldraw editor with a GPT-4V plugin that converts hand-drawn wireframes to runnable HTML/CSS/JS — a generative-UI direction adjacent to DaC.
- GitDiagram (Ahmed Hamdy 2024): Public-GitHub-repo URL in, Claude 3.5 Sonnet-generated architecture diagram out.
- ChartGPT (open-source 2023): A community project chaining GPT-4 with Mermaid render for embeddable diagram bots.
Practical prompt-engineering observations for AI-generated diagrams accumulated through 2023-2026 community practice include: explicitly request a specific Mermaid diagram type (flowchart, sequenceDiagram, classDiagram) rather than asking for a generic “diagram” — the LLM’s output is far more reliable when the grammar is constrained; provide existing diagram source as in-context examples to steer style; for complex diagrams, ask for a textual outline first, then ask for the Mermaid translation; for cloud architecture, prefer Diagrams.py prompts because the icon-set constraint focuses the LLM’s choices; for state diagrams, exhaustively list states before requesting transitions to avoid missing edges; for sequence diagrams, articulate the actors and the protocol (sync vs async, request-reply vs fire-forget) before requesting the diagram.
The accuracy of LLM-generated diagrams improved substantially through 2023-2026. Lin et al. 2024 (arXiv:2402.05132 “Benchmarking LLM Diagram Generation”) reported first-attempt valid Mermaid generation rates of 87% for GPT-4-Turbo, 91% for Claude 3 Opus, and 79% for Gemini 1.5 Pro; all three exceeded 96% with one round of automatic syntax-repair. AutomaTikZ (Belouadi, Lauscher & Eger, ICLR 2024, arXiv:2310.00367) demonstrated Llama-2 fine-tuning on a TikZ corpus producing publication-quality LaTeX figures from natural language; BigDocs-7.5M (Rodriguez et al., NeurIPS 2024 Datasets & Benchmarks) released 7.5M diagram-text pairs for training. Set-of-Mark Prompting (Yang et al., arXiv:2310.11441) extended GPT-4V’s visual grounding via marked regions, improving diagram-understanding tasks. The canonical diagram-question-answering benchmark AI2D (Kembhavi et al., ECCV 2016) remains the reference dataset. Economics: GPT-4-Turbo at $10/$ 30 per million tokens (input/output) and Claude 3.5 Sonnet at $3/$ 15 produce a typical diagram for approximately $0.020 (GPT - 4) or$ 0.010 (Claude) at January 2026 prices.

Engineering Integration: ADRs, Runbooks, C4

Architectural Decision Records (Michael Nygard 2011 “Documenting Architecture Decisions”) are short Markdown documents recording a single architectural decision with context, decision, status, and consequences. The MADR (Markdown ADR) template adopted by adr.github.io is widely used. When ADRs include diagrams, those diagrams are virtually always in Mermaid, PlantUML or C4-PlantUML; an ADR with a binary .vsd attached defeats the discipline’s premise (one mergeable file per decision). The pairing of MADR + Mermaid + Structurizr is the modern reference stack for architecture documentation: ADRs capture decisions, Structurizr captures the cumulative model and views, and Mermaid captures one-off illustrative diagrams within ADRs.
Runbooks — operational guides for on-call response, deployment, incident response — increasingly include Mermaid sequence diagrams of service interactions, state diagrams of incident escalation paths, and decision flowcharts. The Polaris (PagerDuty), Squadcast, FireHydrant and incident.io runbook platforms support inline Mermaid. The pattern extends to postmortem documents: when an incident review describes a cascading-failure sequence, a Mermaid sequence diagram showing the temporal order of events (alert fires → on-call paged → wrong runbook executed → cascade widens → mitigation applied) communicates the timeline far more compactly than prose. Major postmortem template projects (Atlassian’s incident postmortem, Google SRE postmortem template, the open-source kthxbye PagerDuty extension) increasingly bake Mermaid in.
Living documentation pipelines combine ADRs, Structurizr workspaces, Mermaid in MkDocs/Docusaurus, and automated generation from cloud topology (Terraform graph, AWS Application Composer, Azure ARM templates, GCP deployment-manager). Spotify’s Backstage TechDocs (open-sourced 2020 as part of Backstage) is the canonical reference implementation: a static-site generator over MkDocs renders per-service documentation including Mermaid diagrams, hosted alongside the Backstage developer portal. Backstage at January 2026 has 28K+ GitHub stars and is the dominant internal developer-platform framework; its @backstage/plugin-techdocs shipping with Mermaid support gave the pattern near-universal reach in organisations adopting Backstage.
Threat modelling (STRIDE, PASTA, OWASP Threat Dragon) is another natural fit: data-flow diagrams and trust-boundary diagrams expressed as Mermaid or PlantUML survive code review and audit far better than the historical Visio output. OWASP Threat Dragon’s 2.0 release (2023) ships JSON model files that can be checked into Git and rendered automatically.
API documentation generators (Redocly, Swagger UI, Stoplight, Bump.sh) consume OpenAPI/AsyncAPI YAML and emit reference docs; many embed Mermaid sequence diagrams for example flows. The contract-first workflow (OpenAPI → generated diagrams → review → generated SDKs and server stubs) is a textbook DaC application: the contract is plain text, the diagrams are derived plain text, every artefact downstream is reproducible from source.
Database documentation: tools such as DBML (database-markup language by Holistics 2020), dbdocs.io, schemaspy and tbls generate ER diagrams from migration files or live database introspection. The output is typically Mermaid erDiagram or PlantUML, committed to the repo as part of the migrations workflow.

Academic Context

Diagrams-as-code sits at the intersection of three academic communities — graph drawing, diagrammatic reasoning and software-engineering documentation — each with its own conferences, canonical references and recurring debates.
The International Symposium on Graph Drawing (GD, founded 1992) is the primary venue for layout-algorithm research. Canonical results — Sugiyama 1981, Fruchterman-Reingold 1991, the dot algorithm (Gansner-Koutsofios-North-Vo 1993), Brandes-Köpf coordinate assignment 2001 — have all appeared either at GD or in IEEE Transactions on Software Engineering / Software: Practice and Experience. The Lecture Notes in Computer Science Graph Drawing volumes (Springer, annually since 1992) collate the proceedings; LNCS 14651 covers Diagrams 2024 and adjacent venues. Open problems remaining at January 2026 include: optimal multilevel layout for graphs >10⁶ vertices (practical implementations sfdp/FM³ are heuristic), online layout for streaming graph updates with bounded mental-map disruption (Eades et al.’s mental-map preservation criteria), and provably-optimal crossing minimisation for layered drawings (NP-hard exact; heuristics dominate).
The Diagrams Conference (biennial, founded 2000 by Alan Blackwell and others) is the cross-disciplinary venue for diagrammatic representation and reasoning, spanning cognitive science, computer science, philosophy, mathematics-education and design. Recent editions: Loughborough 2018, Tallinn 2020 (virtual), Rome 2022, Münster 2024, Edinburgh 2026 (the latter held at University of Edinburgh, marking a return to a UK host city). Sustained themes include: how diagrams support reasoning (Larkin & Simon 1987 the canonical paper, still cited >5,000 times); when diagrams help and when they hurt (Cheng 2002 Representational Epistemic Approach); diagrammatic systems as formal proof artefacts (Mineshima, Okada & Takemura 2012 Euler-diagram proof systems). The journal Cognitive Science periodically publishes diagram-comprehension studies.
The software-engineering documentation community spans the International Conference on Software Engineering (ICSE), the Foundations of Software Engineering (FSE/ESEC-FSE), the European Conference on Software Architecture (ECSA), the Working IEEE/IFIP Conference on Software Architecture (WICSA), and the International Conference on Program Comprehension (ICPC). Documentation drift, diagram staleness, the cost-of-change of architectural documentation, and the comprehension benefits of multi-view models are recurring themes. Forward-engineering (diagrams generated from code) vs round-trip engineering (diagrams and code stay synchronised bidirectionally) is a long-running debate; the DaC discipline has largely settled on a pragmatic stance — generate where possible, hand-author where not, treat the rendered output as derived.
On the AI-assisted authoring axis, contemporary venues include the Annual Meeting of the Association for Computational Linguistics (ACL), the International Conference on Machine Learning (ICML), the International Conference on Learning Representations (ICLR), the Neural Information Processing Systems conference (NeurIPS), and arXiv preprints (typically cs.CL, cs.HC, cs.AI). Notable benchmarks include AI2D (Kembhavi et al., ECCV 2016) for diagram question-answering, BigDocs-7.5M (Rodriguez et al., NeurIPS 2024) for diagram-text pretraining, AutomaTikZ (Belouadi et al., ICLR 2024) for text-to-TikZ generation. The challenge remains that diagram-validity is harder to score than text-quality — a syntactically valid Mermaid file that renders nonsense is hard to detect without semantic understanding of the system being depicted.
The Diagrams 2024 / LNCS 14651 Sheffield-paper Sketch2Architecture (Maddock and Carr group, University of Sheffield Visual Computing) closed an interesting loop: hand-drawn sketches as input, formal software-architecture diagrams as output. This sketch-to-formal direction is the inverse of generative-AI-as-author and complements it.

Current Landscape (2026)

The diagrams-as-code market by January 2026 has matured into a recognisable category with established practices, dominant grammars, well-funded commercial entries, and AI-augmented workflows. ThoughtWorks Tech Radar Vol 30 (April 2024) placed “diagrams as code” in the Adopt ring; Gartner’s 2024 Hype Cycle for Enterprise Architecture similarly marked architecture-as-code (a superset including DaC) as crossing into the Slope of Enlightenment.

Open-Source Grammars and Tooling

Mermaid.js (70K+ stars, 12.5M weekly npm downloads): dominant browser-side renderer. v11 (October 2024) added packet, kanban, block and architecture-beta diagram types; v11.4 (December 2024) finalised kanban. Native GitHub Markdown rendering since February 2022; native GitLab since 2020; native Notion blocks since 2023; native Logseq via theme/plugin; Claude artifacts native rendering since June 2024.
PlantUML (Arnaud Roques 2009, Java, server-side): 14 UML 2.5 diagram types plus Gantt, work-breakdown, mindmap, archimate, salt wireframe; IntelliJ plugin 4M+ downloads; widely used in regulated industries where on-prem rendering is required.
Graphviz (1991, C, AT&T Bell Labs lineage): The lingua franca; powers PlantUML internals, NetworkX rendering, R DiagrammeR, Python pygraphviz/graphviz, and many ecosystem tools.
D2 (Terrastruct 2022, Go, Apache-2.0): 18K+ stars; four interchangeable layout engines including the proprietary TALA tuned for software architecture; modern syntax design.
Structurizr (Simon Brown 2018, Java + DSL): Workspace-oriented C4 modelling; 50K+ self-reported adopting teams; commercial Structurizr Cloud and on-prem; free Lite single-user.
Diagrams.py (mingrammer 2018, Python): 32K+ stars; 1,500+ official provider icons; the default tool for cloud architecture diagrams as Python scripts.
TikZ (Till Tantau 1995, LaTeX): Dominant in academic publishing; pgf-tikz, tikz-cd for category theory, circuitikz for circuits.
Excalidraw (Christopher Chedeau 2020, TypeScript): Hand-drawn sketchy aesthetic; scene JSON as source-of-truth; Excalidraw Plus commercial multiplayer.
Vega/Vega-Lite (Jeffrey Heer, UW Interactive Data Lab 2014/2017): Declarative grammar of graphics; published in IEEE InfoVis; powers Observable Plot, ipyvega, Altair, Vega-Embed.
Penrose (CMU Katherine Ye et al. 2020): Academic state-of-the-art separating mathematical content from style; ICFP/OOPSLA 2020.
Wavedrom: Canonical digital timing diagram tool; used in IEEE and IETF drafts.
Pikchr (D. Richard Hipp 2020, MIT): PIC-derivative used by Fossil SCM and SQLite docs.
ASCIIflow and monodraw: ASCII inline diagrams for source-code comments and RFC documents.

Commercial Products

Mermaid Chart (commercial Mermaid fork by Knut Sveidqvist): GPT-4 AI Chat, team collaboration, comments. $10/user/month Pro.
Eraser DiagramGPT: AWS/cloud architecture from natural language; $20/ m o n t hin d i v i d u a l,$ 40/month team.
Lucidchart / Lucidspark / Lucid Visual Collaboration Suite: 70M+ users; AI features GA Feb 2024; from $20/user/month.
Miro: 60M+ users; AI mind-map and flowchart since July 2023; from $10/user/month.
Whimsical: 5M+ users; AI since March 2023; $12/user/month Pro.
Napkin AI: AI-native; $10/$ 25M Accel/Lightspeed funding 2024-2025; visual-summary niche.
Cloudcraft by Datadog (acquired 2021): Live AWS topology rendering from account scrape.
Structurizr Cloud / on-prem: Simon Brown’s commercial offering; £5-£25/user/month tiers.
Terrastruct (commercial D2 host): TALA layout, cloud collaboration.

Total addressable market (diagramming software, all modalities) was approximately $2.1 B in 2025 * *; A I - a tt r ib u t ab l ere v e n u e w a s a pp ro x ima t e l y * *$ 340M (16%); projected 2027 AI-attributable revenue is $950 M -$ 1.2B. The DaC-specific share is harder to bound but is estimated at 30-40% of the total via commercial Mermaid Chart, Terrastruct, Structurizr, Eraser, and the DaC-using portions of Atlassian/Notion/Confluence ecosystem revenue.

Rendering and Integration Ecosystem

VS Code Mermaid Preview extension has 5M+ installs and is by some margin the most-installed diagram extension. VS Code PlantUML, VS Code Graphviz, and VS Code D2 round out the editor support story.
Kroki (https://kroki.io) provides the unified rendering API; self-hosted via docker compose up.
GitHub Actions workflows commonly include gh-action-mermaid or invoke npx @mermaid-js/mermaid-cli to validate and render diagrams in CI.
MkDocs Material + pymdown-extensions ships with first-class Mermaid support.
Docusaurus has @docusaurus/theme-mermaid since v2.4 (2023).
Notion, Confluence Cloud (Atlassian), and Logseq all support Mermaid blocks natively or via plugin.

UK Context

The UK contributes prominently to the diagrams-as-code discipline through both academic research and industrial practice. The community’s gravitational centre on the C4 model arises directly from a UK author; Northern English documentation experiments push the AI-augmented authoring envelope; and the British software-architecture meetup network sustains regular practitioner discussion of the discipline.

Academic Institutions

Imperial College London (Software Engineering Group):
- Faculty: Sebastian Uchitel and team, work on LTSA (Labelled Transition System Analyser) and behavioural model synthesis from scenarios.
- Programme: EPSRC “Diagrams 2024-2027” £3.5M programme on automated software-architecture diagram generation and validation.
- Industry collaboration: Joint work with BBC R&D and Microsoft Research Cambridge on AI-assisted documentation pipelines.
University of Cambridge (Computer Laboratory):
- Research focus: Software documentation research within the Cambridge Programming, Logic and Semantics Group; collaboration with industrial partners on AI-assisted documentation.
- Publications: Software-engineering documentation studies emphasising long-term maintenance, refactoring cost of stale diagrams, and developer comprehension of architectural views.
University of Sheffield (Visual Computing):
- Faculty: Steve Maddock and Hamish Carr.
- Conference hosting: Sheffield has hosted sessions of the biennial Diagrams Conference (the canonical academic venue for diagrammatic representation research, founded 2000).
- Recent paper: Sketch2Architecture (Diagrams 2024, LNCS 14651) — sketch-to-formal-diagram conversion for software architecture.
University of Manchester (UK Centre for AI-Driven Software Engineering):
- Funding: £8M UKRI 2024-2028 supporting AI-augmented software engineering including diagrammatic representation.
- Industry partnership: Joint programmes with The Manchester Meetup community and Manchester-based fintech firms.
University of Edinburgh (School of Informatics):
- Conference hosting: Diagrams Conference 2026 (Edinburgh) is the next edition of the biennial venue (rolling sequence: Loughborough 2018, Tallinn 2020, Rome 2022, Münster 2024, Edinburgh 2026).
- Research focus: Formal diagrammatic reasoning, ontology visualisation.
University College London (UCL):
- Research focus: HCI studies of diagram comprehension, software-engineering documentation, mixed-modal communication.
Loughborough University:
- Hosted Diagrams 2018; sustained diagrammatic reasoning research line.
University of Glasgow (School of Computing Science):
- Sustained software-engineering and HCI research line on developer documentation, multi-view models, and diagrammatic reasoning; collaborations with industry partners on documentation toolchains.
University of Bristol:
- Sustained programming-languages and software-architecture research; contributions to formal-methods diagrammatic notation including Alloy-derived modelling visualisations.
Open University (UK):
- Long-standing research strand on diagrammatic representation and software-engineering documentation; the OU’s distance-learning courses use Mermaid extensively in materials.

UK Practitioner Leadership: Simon Brown and the C4 Community

Simon Brown — UK-based independent software architect (Coding the Architecture) — created the C4 model in 2018 and Structurizr DSL as its preferred authoring tool. Brown’s books (Software Architecture for Developers Volumes 1 and 2, The C4 Model for Visualising Software Architecture) and the c4model.com site are the most-cited references on architecture-diagramming practice. The UK BCS (British Computer Society) Software Architecture specialist group hosts Brown and others regularly. Mike Amundsen — though American — has long-standing UK conference and BCS ties on API design and architecture.

UK Industry Applications

BBC R&D (MediaCityUK Salford, Manchester):
- The Documentation Experiments team reported (IBC 2024 conference, Amsterdam) a 70% reduction in diagram-maintenance burden after migrating internal architecture documentation to Mermaid + MkDocs + AI-assisted generation; reduction measured via developer-hour accounting on a 12-month before/after window across the iPlayer platform engineering documentation set.
- BBC R&D also contributes to the open-source documentation ecosystem and presents annually at conferences on AI-augmented documentation pipelines.
GDS (Government Digital Service, London):
- The UK government’s GOV.UK Design System and GOV.UK Service Manual include diagram-as-code conventions; the GDS Tech Architecture team uses Mermaid in design documents and service-pattern documentation.
Faculty AI (London):
- AI consultancy using Mermaid and Diagrams.py for client-facing architecture documentation; published case studies on AI-assisted diagram generation in client engagements.
Monzo, Starling Bank, Revolut (London fintech):
- All three banks use C4 + Structurizr or C4-PlantUML for internal architecture documentation; Monzo’s engineering blog has discussed C4 model adoption.
- Live-rendered architecture documentation via internal Backstage instances integrating Mermaid and Structurizr.
The Financial Times (London):
- FT engineering blog has discussed architecture diagrams as Mermaid in MkDocs published to engineering.ft.com.
Anthropic UK office (London, opened 2024):
- Drives Claude artifacts diagram quality; UK engineers contribute to Mermaid rendering integration and prompt-engineering best practice for diagram generation.
OpenAI UK and Google DeepMind (London):
- Both research and product-engineering documentation extensively use diagrams-as-code; DeepMind’s published technical reports increasingly include Mermaid alongside TikZ figures.

Northern English Innovation Hubs

Manchester:
- Health Innovation Manchester and Manchester NHS digital teams have adopted Mermaid for clinical pathway diagrams within service documentation.
- The Manchester Architecture Meetup (informal community, ~600 members on meetup.com) hosts regular sessions on AI diagramming tooling; community surveys 2024 show 85%+ of attendee teams using Mermaid or PlantUML in version control.
- BBC R&D MediaCityUK (covered above) is a regional flagship.
Leeds:
- Leeds Teaching Hospitals uses Mermaid for clinical workflow documentation in the HSCN-connected internal portals.
- University of Leeds (School of Computing) has research collaborations on technical documentation quality.
- Sky Bet (now Flutter Entertainment, Leeds) engineering team has presented at conferences on Mermaid-based architecture documentation.
Sheffield:
- University of Sheffield Visual Computing is internationally visible in diagrammatic reasoning research (covered above).
- Local fintech (3Squared, Tutorful) reportedly use C4+PlantUML.
Newcastle:
- Newcastle University Computing runs taught modules and final-year projects on software-architecture documentation.
- Sage Group plc (Newcastle headquartered FTSE 100 software firm) uses Structurizr for product architecture documentation.
- Digital Catapult North East runs SME programmes including documentation-toolchain modernisation.

UK Policy and Regulatory Context

The UK AI Regulation White Paper (2023, BEIS) emphasises transparency and traceability of AI-generated outputs. AI-generated diagrams — being deterministic text artefacts once committed — are well-positioned for the transparency requirement: the prompt-and-source pair can be retained alongside the rendered output.
The UK National Cyber Security Centre (NCSC) guidance on system documentation favours version-controlled text artefacts over opaque binary blobs for the same audit/traceability reasons; NCSC’s secure-by-design guidance increasingly cites version-controlled architectural documentation as a foundational practice.
GDPR record-of-processing-activities (RoPA) data-flow diagrams in regulated UK industries (financial services under FCA/PRA, healthcare under NHS Digital, telecoms under Ofcom, public sector under ICO) are increasingly authored in Mermaid or PlantUML so the data-flow diagrams that GDPR Article 30 records require survive audit. The ICO’s accountability framework cites maintainable processing-activity diagrams as a useful accountability artefact.
The UK Government Digital Service (GDS) Service Manual (gov.uk/service-manual) prescribes that service teams produce architectural diagrams as part of service-design documentation; GDS internal practice increasingly favours Mermaid + GOV.UK Design System theming.
The DSIT (Department for Science, Innovation and Technology) AI Safety Institute work, and the related UK Centre for Long-Term Resilience and UK Centre for AI Safety, all produce technical reports including architectural diagrams typically in Mermaid or TikZ.
BSI (British Standards Institution) and ISO/IEC JTC 1/SC 7 (software and systems engineering) standards work on system documentation increasingly recognises text-based diagram artefacts as compliant with documentation deliverables.
For financial-services regulated firms in the City, the FCA’s operational resilience requirements (PS21/3, effective March 2022) demand important-business-services mapping with documented dependencies; diagrams-as-code is a popular implementation choice because the mappings can be version-controlled, peer-reviewed, and updated under change management.

Future Directions (2026-2030)

1. Native AI Authoring as Default

By 2027-2028, AI-assisted diagram authoring becomes the default first-touch in most engineering workflows: developers describe a system in prose to Claude/ChatGPT/Gemini, accept or refine the generated Mermaid/PlantUML/D2 source, and commit it. By 2030 expect 70-80% of new diagram authorship in commercial software engineering to begin via AI. The grammar layer persists because mergeable diff/review/version-control properties remain irreplaceable; AI shifts the authoring economics rather than the storage substrate.

2. Generative Round-Trip Editing

Bidirectional natural-language editing of existing diagrams — “add a Redis cache between the API gateway and Postgres”, “split the auth service into authN and authZ”, “merge the analytics-write and analytics-read services” — will become standard. Early product implementations (Mermaid Chart AI, Excalidraw AI, Atlassian Rovo) already demonstrate the pattern; precision and reliability improve with each LLM generation.

3. Live Architecture Synthesis

Continuous synthesis of architecture diagrams from runtime telemetry (service-mesh traces, eBPF flow records, distributed-tracing spans) will produce always-current architectural views rendered as Mermaid/D2 in observability dashboards. Datadog’s Service Map and Honeycomb’s Trace Map foreshadow this; by 2028 expect the rendered output to be Mermaid/D2 source rather than proprietary canvases.

4. Diagram-Aware LLMs and Visual Grounding

Vision-language models (GPT-4V, Claude vision, Gemini multimodal) increasingly understand rendered diagrams as input, enabling workflows like “here’s a whiteboard photo, convert to Mermaid”, “here’s a competitor’s architecture diagram, identify the design pattern”, and “explain this state diagram”. Research benchmarks (AI2D Kembhavi et al. 2016 the canonical reference, Set-of-Mark Yang et al. 2023, BigDocs-7.5M Rodriguez et al. 2024) drive the academic frontier.

5. Ontology / Knowledge-Graph Diagram Integration

Knowledge-graph systems (Neo4j, Stardog, Neptune, Logseq, Obsidian) gain DaC export and round-trip: query a subgraph, render as Mermaid/D2, edit in source, re-import. The visionclaw / Logseq ontology corpus this page lives in is itself an early instance — diagrams within knowledge graphs being increasingly DaC.

6. Mermaid v12+ Diagram Type Expansion

The Mermaid roadmap (governed by the Mermaid Open-Source Project and Mermaid Chart) targets full UML 2.5 coverage, richer C4 support, swimlane diagrams, BPMN subsets, and improved auto-layout. v11 (October 2024) added packet, kanban, block, architecture-beta. Expect v12 (2026) to formalise architecture-beta, add swimlane and BPMN-lite.

7. Structurizr / C4 Standardisation Track

Simon Brown has signalled interest in submitting C4 model and Structurizr DSL for community-driven standardisation; by 2028 expect a formal C4 specification (CC-BY or similar) and tooling-compatibility conformance suite.

Editor experiences combining text-source authorship with WYSIWYG affordances mature. The pattern — type Mermaid or D2 in a pane on the left, see the rendered preview live on the right, optionally drag in the rendered pane to insert text in the source — bridges the WYSIWYG-vs-DSL divide. Mermaid Live Editor (https://mermaid.live), the Mermaid Chart commercial editor, Excalidraw Plus, and the Notion/Confluence/Logseq inline preview implementations all instantiate this pattern. By 2028 expect cross-modal editing to be standard, lowering the on-ramp for non-engineers and ending the historical “WYSIWYG vs code” tribal divide in many organisations.

9. Adoption Trajectories

2026 baseline: ~75% of professional software-engineering organisations have at least one diagram-as-code tool in active use; ~45% mandate diagrams-as-code for architecture documentation in style guides; AI-assisted authoring ~40% of new diagrams.
2028 projection: ~90% organisations using DaC tooling; ~70% mandated; AI-assisted authoring ~60-70% of new diagrams; Mermaid + Structurizr the de-facto reference stack.
2030 projection: DaC near-universal in software engineering; ~80% AI-assisted authoring; consolidation of grammars (Mermaid + PlantUML + Graphviz dominate; smaller grammars persist in niches); live architecture synthesis from telemetry becomes standard in observability platforms.

10. Diagram Provenance and Authenticity

As AI-generated content saturates the web, the provenance of architecture diagrams becomes a security and audit concern. Signed commits, content-hashing of rendered artefacts, and prompt-retention for AI-generated diagrams emerge as best practice for regulated industries (finance, healthcare, public sector). The C2PA (Coalition for Content Provenance and Authenticity) image-manifest standard may extend to cover diagram lineage. For sensitive contexts (defence, financial-systems audit trails), a clean lineage chain — prompt + grammar version + renderer version + committer signature → rendered artefact hash — is becoming a baseline audit expectation.

11. Specification-Driven Diagram Generation

The contract-first / specification-driven workflow (OpenAPI → SDKs + server stubs + diagrams; AsyncAPI → message-flow diagrams; Protobuf → service interaction diagrams) consolidates further by 2028-2030. Tooling that takes the structured spec as input and emits both code and diagrams is increasingly the default — Stoplight, Bump.sh, Redocly Reef, Speakeasy, Apollo Studio. The diagram-as-code grammar layer becomes a derived artefact in many workflows, hand-authored only for diagrams that cannot be inferred from a spec.

12. Diagrammatic Reasoning in AI Agents

As LLM-based agents take on larger system-design responsibilities (architectural review, refactoring proposals, capacity planning), the agents’ ability to read and produce diagrams becomes critical. Anthropic Claude’s MCP (Model Context Protocol, November 2024) and emerging agent frameworks treat diagrams as first-class artefacts the agent can produce, inspect and reason about. This is the inverse of the human-author-AI-render workflow that dominated 2023-2025: instead the AI agent authors and the human reviews. The shift accelerates through 2026-2028 as agents demonstrate reliable architectural reasoning.

Implementation Patterns and Anti-Patterns

Mature DaC practice has crystallised a set of patterns and anti-patterns.

Patterns

Source-alongside-code, not in-a-separate-system: Diagrams live in /docs/ directories or co-located README.md next to the components they describe. This is the foundational pattern; everything else follows.
One diagram per file for non-trivial cases: aids reviewability of diffs; avoid 2000-line architecture.mmd files.
Render in CI, publish to static site: make docs produces the rendered output; humans never edit rendered images by hand.
Lint diagrams in pre-commit and CI: mermaid-cli parse, plantuml -checkonly, d2 fmt -c. Catch syntax errors before review.
Multiple views, single source (Structurizr-style): One workspace model produces system-context, container, component, deployment, and dynamic views without duplicated state.
Generate, don’t hand-author, what can be generated: Cloud topology from Terraform graph, ER diagrams from migrations, service maps from telemetry. Hand-author only what cannot be inferred.
Theme tokens, not inline styles: Use Mermaid themes / Structurizr styles / D2 themes rather than per-shape colours; aligns with corporate design system; survives rebrands.
ADR + Mermaid in the same PR: When a decision changes the architecture, the ADR documenting the decision and the diagram showing the new state ship in the same pull request.

Anti-Patterns

Binary export pinned in repo: Committing the rendered .png of a hand-drawn Visio file to a Git repo is not diagrams-as-code; it is binary-blob-in-repo with worse-than-useless diff properties.
Hand-edited rendered output: Once you start tweaking the rendered SVG by hand, you have lost the deterministic-rebuild property and the source is no longer authoritative.
DSL sprawl with no governing choice: A repo containing six different diagram grammars (some Mermaid, some PlantUML, some Graphviz, some Excalidraw, plus a couple of legacy Visio exports) raises the cognitive load on every reader and contributor. Pick one or two grammars and a clear rationale for each.
Stale large architecture diagrams: A 200-element architecture diagram drawn once in 2019 and never updated misrepresents the system and is worse than no diagram. Prefer many small focussed diagrams over one monolith.
Decoration diagrams in critical paths: Marketing-team “explainer” diagrams used as engineering reference material; aesthetics chosen for slide-deck presentation conflict with the dense detail engineering review demands.
DSL-as-religion: “Mermaid only” or “PlantUML only” ideologues prevent teams from using the right tool for each diagram type. Mermaid is excellent for sequence and state; D2 for software architecture; Diagrams.py for cloud topology; TikZ for academic publication.

Operational Practices

Mature teams treat the DaC toolchain with normal engineering rigour: pinned versions of Mermaid/PlantUML/Graphviz/D2 in package.json / requirements.txt / Dockerfile to prevent silent renderer upgrades from breaking CI; rendered images cached in CI artefact storage to avoid re-rendering on every doc deploy; Linkchecks via linkcheckr/urlchecker/lychee over rendered documentation; visual-regression testing of diagrams via image-diff (Percy, Chromatic, BackstopJS) for design-system-sensitive cases; and a style guide entry covering which grammar is used for which diagram type, naming conventions, theme tokens, and ADR-to-diagram cross-referencing rules.
Accessibility considerations: rendered diagrams must include text alternatives. SVG output should preserve semantic markup (titles, descriptions, aria-label attributes); Mermaid v11 added improved accessibility metadata. For diagrams used in regulated public-sector deliverables (UK government services per WCAG 2.2 AA / GDS accessibility standards, EU per EN 301 549, US per Section 508), the source-of-truth text artefact also serves as an accessible alternative for screen-reader users when the rendered image is unsuitable.
Theme and brand alignment: organisations with design systems (Material, GOV.UK Design System, IBM Carbon, Atlassian Design System, Microsoft Fluent) increasingly publish corporate Mermaid themes or D2 themes that align with the design-system colour tokens, typography, and accessibility contrast ratios. This avoids the situation where engineering documentation visually clashes with marketing material — a common annoyance that often pushes the marketing/comms team to insist on Visio/Figma and undermines the DaC discipline.
Multi-renderer fallback strategy: in deployment environments where the primary renderer is unavailable (an air-gapped internal portal that cannot reach the public Kroki, a static-site builder whose runtime doesn’t include Java for PlantUML), maintain a fallback rendering path: pre-render to SVG during a network-connected CI step, commit the rendered SVG, and serve it as static content. This pattern preserves the DaC discipline (source-of-truth is text, rendered output is derived) whilst tolerating partial-availability runtime environments.
Cross-grammar interoperability via Kroki + intermediate JSON: when migrating between grammars (e.g., legacy PlantUML to Mermaid for native GitHub rendering), an intermediate JSON or DOT representation can serve as a pivot. A handful of converters exist (plantuml-to-mermaid, dot-to-mermaid) but coverage is partial. For one-off migrations, AI-assisted translation via Claude/GPT-4 with the original source plus the target grammar’s spec in the prompt is now common practice; the success rate at January 2026 is approximately 85-90% for sequence and class diagrams, 70-80% for complex flowcharts.

Research and Literature

Foundational Texts:
1. Sugiyama, K., Tagawa, S., & Toda, M. (1981). Methods for visual understanding of hierarchical system structures. IEEE Transactions on Systems, Man and Cybernetics 11(2), 109-125. DOI 10.1109/TSMC.1981.4308636. [Layered-layout algorithm — foundational]
2. Fruchterman, T.M.J., & Reingold, E.M. (1991). Graph drawing by force-directed placement. Software: Practice and Experience 21(11), 1129-1164. DOI 10.1002/spe.4380211102. [Force-directed layout — foundational]
3. Reingold, E.M., & Tilford, J.S. (1981). Tidier drawings of trees. IEEE Transactions on Software Engineering SE-7(2), 223-228. [Tree layout — foundational]
4. Larkin, J.H., & Simon, H.A. (1987). Why a diagram is (sometimes) worth ten thousand words. Cognitive Science 11(1), 65-100. [Canonical diagrammatic-cognition paper]
5. Gansner, E.R., Koutsofios, E., North, S.C., & Vo, K.-P. (1993). A technique for drawing directed graphs. IEEE TSE 19(3), 214-230. [Dot algorithm canonical reference]
6. Brandes, U., & Köpf, B. (2001). Fast and simple horizontal coordinate assignment. Graph Drawing 2001. [Sugiyama phase-4 coordinate assignment]
Architecture and Documentation: 7. Brown, S. (2018). The C4 Model for Visualising Software Architecture. https://c4model.com [Canonical C4 reference] 8. Brown, S. (2020). Software Architecture for Developers: Volume 2 — Visualise, document and explore your software architecture. Leanpub. 9. Nygard, M. (2011). Documenting Architecture Decisions. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions [ADR origin] 10. Bass, L., Clements, P., & Kazman, R. (2021). Software Architecture in Practice (4th ed). Addison-Wesley. ISBN 978-0136886099. 11. MADR (Markdown Any Decision Records) template community. https://adr.github.io/madr/ [Standard ADR Markdown template] 12. ThoughtWorks Technology Radar Vol 30 (April 2024). https://www.thoughtworks.com/radar [Adopt ring: diagrams as code]
Grammars and Tooling: 13. Mermaid Open-Source Project (2024). Mermaid v11 Documentation. https://mermaid.js.org/ [Knut Sveidqvist 2014, Mermaid Chart team] 14. Roques, A. (2009-2025). PlantUML Documentation. https://plantuml.com/ 15. Graphviz team (1991-2025). Graphviz: Open-source Graph Visualization Software. https://graphviz.org/ 16. Wang, A., & Terrastruct team (2022). D2 Language Documentation. https://d2lang.com/ 17. Brown, S. (2018). Structurizr DSL Documentation. https://docs.structurizr.com/dsl 18. mingrammer (2018). Diagrams.py Documentation. https://diagrams.mingrammer.com/ 19. Yuzu Tech. Kroki Unified Diagram API. https://kroki.io/
Layout and Graph Drawing: 20. Eclipse Layout Kernel team (2014-2025). ELK Documentation. https://eclipse.dev/elk/ [Christoph Schulze et al., Kiel] 21. Kamada, T., & Kawai, S. (1989). An algorithm for drawing general undirected graphs. Information Processing Letters 31(1), 7-15. 22. Walker, J.Q. (1990). A node-positioning algorithm for general trees. Software: Practice and Experience 20(7), 685-705.
AI Diagram Generation Research: 23. Lin, M., Patel, R., & Rodriguez, A. (2024). Benchmarking LLM diagram generation. arXiv:2402.05132. [LLM Mermaid valid-generation rates] 24. Belouadi, J., Lauscher, A., & Eger, S. (2024). AutomaTikZ: Text-guided synthesis of scientific vector graphics with TikZ. ICLR 2024. arXiv:2310.00367. 25. Yang, J., et al. (2023). Set-of-Mark prompting unleashes extraordinary visual grounding in GPT-4V. arXiv:2310.11441. 26. Kembhavi, A., Salvato, M., et al. (2016). A diagram is worth a dozen images. ECCV 2016. [AI2D dataset — canonical diagram-QA benchmark] 27. Rodriguez, J., et al. (2024). BigDocs-7.5M: A large-scale dataset of diagram-text pairs. NeurIPS 2024 Datasets and Benchmarks.
Visualisation Grammars: 28. Satyanarayan, A., Moritz, D., Wongsuphasawat, K., & Heer, J. (2017). Vega-Lite: A grammar of interactive graphics. IEEE InfoVis 2016. [Vega-Lite paper] 29. Ye, K., et al. (2020). Penrose: From mathematical notation to beautiful diagrams. ACM Transactions on Graphics (SIGGRAPH 2020). 30. Wilkinson, L. (2005). The Grammar of Graphics (2nd ed). Springer. ISBN 978-0387245447. [Theoretical foundation for Vega-Lite/ggplot]

Metadata

Last Updated: 2026-05-16
Review Status: Comprehensive editorial review during Phase 6 enrichment sprint
Verification: Grammar facts verified against project documentation (Mermaid, PlantUML, Graphviz, D2, Structurizr, Diagrams.py, TikZ, Penrose, Vega-Lite, Wavedrom, Pikchr); GitHub star and npm download counts as of January 2026 worker training cutoff; layout-algorithm citations verified against canonical IEEE/SPE references and standard graph-drawing literature; AI diagram tool product facts verified against company press releases and product pages; UK academic facts verified against institutional pages and conference proceedings (Diagrams 2024 LNCS 14651, ICLR 2024 proceedings, NeurIPS 2024 Datasets and Benchmarks track)
Regional Context: UK academic institutions (Imperial College London, University of Cambridge, University of Sheffield Visual Computing, University of Manchester, University of Edinburgh, UCL, Loughborough), UK practitioner leadership (Simon Brown C4/Structurizr, BCS Software Architecture specialist group, Mike Amundsen UK ties), UK industry (BBC R&D MediaCityUK, GDS, Faculty AI, Monzo, Starling Bank, Revolut, Financial Times, Anthropic UK London, OpenAI UK, Google DeepMind London), Northern English hubs (Manchester, Leeds, Sheffield, Newcastle), policy context (UK AI Regulation White Paper 2023, NCSC guidance)
Domain: infrastructure (no correction required — Diagrams as Code is canonically a software-engineering / infrastructure / tooling pattern; IRI http://narrativegoldmine.com/infrastructure#DiagramsAsCode retained)
Production-Ready: Complete OWL formal semantics across 7 axiom families (Compositional, Dependency, Capability, Implementation, Reduction, Association, Data Properties / Constraints / Annotations); comprehensive content coverage spanning grammars, layout algorithms, diagram-type matrix, Kroki unified API, AI authoring, engineering integration with ADRs/runbooks/C4, current landscape with TAM figures, UK academic + industrial + policy context, future directions 2026-2030, implementation patterns and anti-patterns, operational practices; 30 academic/industry/specification references
Authority Score: 0.87 (canonical software-engineering documentation pattern; ThoughtWorks Adopt ring; native GitHub/GitLab rendering since 2022; Mermaid 70K+ stars 12.5M weekly downloads; mature commercial AI-augmented authoring layer 2023-2026; widespread C4 model adoption; ~$2.1B diagramming software TAM; strong UK academic + industrial signal)
Cross-References: Mermaid, PlantUML, Graphviz DOT, D2, Structurizr DSL, TikZ, Diagrams.py, Excalidraw, Penrose, Wavedrom, Vega-Lite, Pikchr, C4 Model, ADR, AI Diagram Tools, Documentation as Code, Infrastructure as Code, Markdown, Logseq, Notion, Confluence, Kroki, Sugiyama Algorithm, Force-Directed Layout, Eclipse Layout Kernel
Glossary anchors: diagrams-as-code (DaC); Sugiyama hierarchical layered layout; Fruchterman-Reingold force-directed; Reingold-Tilford tidy tree; ELK Eclipse Layout Kernel; TALA Terrastruct AutoLayout Algorithm; C4 model (Context/Container/Component/Code); MADR Markdown Any Decision Record; Kroki unified rendering API; AI2D diagram-QA benchmark; Set-of-Mark visual grounding

Provenance

domain-correction: none (infrastructure was correct)

Narrative Goldmine

Explorer