Diagram-as-code tools are just a step towards the tools we need

Software architecture is the backbone of any successful project. Architects, DevOps engineers, and platform teams need effective ways to visualize complex systems, align stakeholders, and facilitate collaboration. Diagrams play a crucial role in quickly getting everyone on the same page before jumping into code, minimizing misunderstandings and reducing rework.

With advancements in AI, there's been an explosion of tools designed to create interactive system design diagrams, building on the diagram-as-code trend that has gained traction in recent years.

Diagram-as-code has been a game-changer for developers, allowing them to generate and manage architecture diagrams directly from plain text or code syntax. It eliminates the need for drag-and-drop whiteboard tools, enabling teams to version control diagrams, integrate them into CI/CD workflows, and generate them programmatically.

While diagram-as-code tools excel at generating diagrams, but they don’t solve a key challenge: keeping them up to date as the system evolves.

And this is where we need to shift the conversation. Automation in diagram maintenance is the missing piece—one that, for example, OpenTelemetry-based system visualization tools are now tackling.

Diagram-as-code Tools

Developers have always sought ways to visualize system architecture, especially in complex projects where diagrams clarify relationships between components far better than written documentation ever could.

From the earliest tools in the 1980s — such as CASE (Computer-Aided Software Engineering) tools which could generate diagrams from code in structured programming environments — to UML (Unified Modeling Language) tools in the 1990s — that could reverse-engineer code into diagrams — software teams have long experimented with code-driven visualization.

For a while, drag-and-drop diagramming tools—Visio, Lucidchart, Draw.io, and others—dominated. While useful, they introduced significant challenges:

• Manual effort: Adjusting boxes and arrows in large projects is time-consuming.
• Lack of version control: No easy way to track changes or collaborate effectively.
• Limited integration: No direct connection to code repositories or automated workflows.

That’s why diagram-as-code (DAC) tools— such as Mermaid, PlantUML, Diagrams and many others —have gained traction. Whether labeled as text-to-diagram tools, diagramming notations, or code-generated visualizations, they all serve a similar purpose:

• Version control & automation: Diagrams are stored as code, allowing tracking, diffs, and automation in CI/CD pipelines.
• Integration with development workflows: Developers can embed diagrams directly into documentation, wikis, and even codebases.
• Concise syntax: Rather than manually drawing, developers describe system components and relationships in a structured format, making diagrams easier to maintain and regenerate as the system evolves.

Most importantly, diagram-as-code makes architecture diagrams more accessible to the entire engineering team. Clear, visual representations of complex architectures, database schemas, and process flows remain one of the most powerful tools for communication and alignment in software development.

Why Diagram-as-code Tools Are Not Enough

Diagram-as-code tools are a significant improvement over traditional drag-and-drop diagramming, offering faster and more accurate system visualizations. However, they still suffer from a fundamental limitation: they remain static snapshots of your system.

While these tools integrate better with development workflows, they don’t address one of the biggest pain points in system architecture—keeping diagrams in sync with reality.

Yes, you could build automation pipelines to regenerate diagrams as your software evolves. You could even develop custom tooling to maintain architectural documentation dynamically. But let’s be honest—most teams don’t have the bandwidth to engineer and maintain such a system alongside their actual product development.

Ultimately, if you add a new service to your system, if an API change, if your architecture evolves, you need to update your Mermaid.js or PlantUML diagram code yourself.

There are other drawbacks as well:

• Diagram-as-code diagrams often lack critical context—such as design decisions, trade-offs, and environment-specific details. Without this information, teams still need to manually track and document key aspects of the systems’ evolution.
• Most diagram-as-code tools focus only on visualization. Some may include documentation features, but few (if any) support other tools an engineer needs to manage a distributed system: platform debugging, collaborative architecture design, implementation of the designed changes.

The bottom line is that diagram-as-code tools are a step forward from whiteboarding tools, but they don’t fully solve the problem of system visibility and management.

Engineers need more than just static diagrams—they need living, automatically updated views of their systems that provide real-time insights into architecture, dependencies, and system behavior.

Truly Interactive Tools

The need to visualize a system isn’t just about seeing how it looks—it’s about understanding how it works so developers can safely make changes, troubleshoot issues, onboard new team members, plan for technical debt, or navigate dependencies in complex architecture.

This is why a real-time visual representation of your system—one that accurately mirrors its current state—is such an incredibly powerful tool for faster decision-making and safer development.

Many tools claim to be "interactive," implying that they support this level of visibility into your system. However, that word can mean very different things. Ask yourself, does "interactive" mean…

• AI-assisted suggestions and modifications?
• Real-time multiplayer collaboration on a shared canvas?
• That the tool is actually connected to your live system, dynamically updating as your software evolves?

Most tools focus on the first two definitions—AI-powered tweaks or real-time editing—but very few offer true interactivity, where the diagram itself is a reflection of the system as it runs.

The Next Generation of System Visualization

A new category of tools is emerging—one that automates architecture documentation by pulling live data from real, running systems.

Built on open-source observability technologies like OpenTelemetry, these tools provide a continuously updated view of system components, dependencies, and interactions.

One example is Multiplayer, which leverages OpenTelemetry to auto-document your system (components, APIs, dependencies, etc.), while also allowing you to design and debug live distributed systems with real-time collaboration.

Conclusion

If you need quick, static visuals, a drag-and-drop whiteboarding tool will do the job—just don’t expect it to stay relevant.

If you want a diagram that’s easy to generate and version-controlled, diagram-as-code tools are a solid step forward.

But if you need a continuously updated, real-time view of your system—one that evolves with your architecture instead of becoming obsolete—a new generation of truly interactive tools is the way forward.

The best tools don’t just capture architecture; they connect to it.