This text was generated using AI and might contain mistakes. Found a mistake? Edit at GitHub
In landscape of software architecture, the combination of diagrams-as-code and artificial intelligence presents both opportunities and challenges. Jacqui Read, author of “Communication Patterns,” shares insights on how these technologies can enhance architecture documentation when used thoughtfully.
Understanding Diagrams as Code
Diagrams-as-code represents a paradigm shift from traditional diagramming tools like Visio or Draw.io. Instead of manually drawing diagrams, developers write code using domain-specific languages (DSLs) with tools such as PlantUML, Mermaid, or Structurizr. This approach offers significant advantages: diagrams can be versioned with code, diffed for changes, and maintained more easily. Unlike XML-based formats, text-based diagrams allow developers to track modifications meaningfully.
The Role of AI: Helpful but Not Magic
While AI tools like ChatGPT and Claude can assist with diagram generation, Read emphasizes that human expertise remains essential. AI excels at specific tasks—converting diagrams between formats, reordering elements, or generating code from specifications. However, LLMs are prone to hallucinations. When asked overly broad questions, they invent syntax or features that don’t exist. The key is asking precise, specific questions backed by deep understanding of the underlying DSL.
Choosing the Right Tool
Different diagrams-as-code tools serve different purposes. PlantUML, built on Java, supports extensive UML diagram types but faces rendering limitations. Mermaid, JavaScript-based, integrates seamlessly with web platforms but lacks certain features like legends. Structurizr stands apart by maintaining an underlying model that automatically generates views—changing one component updates all related diagrams. This model-driven approach dramatically reduces maintenance burden.
Beyond Structure: Communicating Behavior
A crucial insight from Read’s work is that architecture documentation shouldn’t focus solely on structure. The C4 model captures system components effectively, but users care about system behavior. Sequence diagrams, activity diagrams, and other behavioral representations are equally vital. AI can help generate these, but only if developers understand the DSLs and can validate the output.
Spec-Driven Development: The New Frontier
Read introduces spec-driven development as an emerging approach where documentation specifications—enhanced by AI—drive code generation. This methodology treats documentation not as an afterthought but as a contract. Diagrams-as-code fits naturally into this workflow, embedded within markdown specifications alongside other architectural decisions.
The Trust Question
Perhaps most critically, Read addresses the trust problem with LLMs. Unlike humans who can admit uncertainty, LLMs are optimized to provide answers—even incorrect ones. This fundamental difference means developers must maintain skepticism and employ validation strategies: comparing AI-generated diagrams against actual code, using multiple models to cross-check results, and understanding that no LLM is perfect.
Conclusion
Diagrams-as-code with AI is a powerful combination, but not a replacement for architectural thinking. The technology shines when developers possess solid foundational knowledge, ask specific questions, and maintain healthy skepticism toward generated output. Rather than asking “Can AI generate this?”, the better question is “When is AI genuinely saving time versus introducing risk?” As this field matures, success lies not in blind trust but in thoughtful, informed collaboration between human architects and intelligent tools.