Introduction
How many times have you joined a new team and noticed that their diagrams are outdated or unclear? How many times have you onboarded a new engineer and had to sketch out parts of the architecture to explain the current full picture? Deep down, engineers view diagrams that haven’t been updated in years the same way they view unmaintained open-source libraries. Unreliable.
These scenarios are not only a byproduct of bad architecture diagrams, but a reflection of why manual diagrams just don’t work. This approach of architecture diagrams is dead, and organisations are realising a need for a better approach.
Now with AI tools, this old way of diagramming is incompatible with how engineers and architects work. At the time of this writing, new agentic workflows are being developed for day-to-day software development (coding, testing, documenting, reviewing PRs or ADRs). Latest examples are Claude Code skills or Cascade Agents.MD files.
The problem with diagrams today
The problem with diagrams today is the manual, disconnected, one-off approach to creating them. No wonder engineers avoid spending time on this.
Architecture diagrams weren’t a problem back in the 2000s. Back then, architecture was monolithic, systems were running on-prem (not in the cloud like AWS), and were less complex and served thousands of users instead of millions.
Interviews back then focused more on deeper abstractions (like uploading media to storage, how TCP/UDP work, DNS resolution, etc.). Now these abstractions are handled by commoditised services like AWS S3 or Route 53. Diagramming also evolved for engineering, from drawing simple client-server requests to a backend server to drawing multi-transactions to a fleet of services, websocket/SSE connections to an LLM (ChatGPT), and more.
Architect’s tools and workflows have also evolved. The old-school workflow for an architect is to draw a diagram in a tool like Lucidchart, Miro, or a whiteboard and export it to a PNG/JPG image and stash it in Notion or Confluence with documentation to explain the architecture in that image.
Now multiply that old-school workflow by every team in the organisation. Each one has their own diagrams, drawn at different times, at different levels of detail, using different conventions. Some show the system as it was six months ago. Some show how it was supposed to be, not how it is. Some contradict each other outright. Many teams eventually realise that manual diagramming doesn’t scale as systems get more complex.
Not having a centralised workspace for collaboration and discussion over architecture makes these diagrams less trustworthy and harder to maintain.
Diagrams are outputs, not a source of truth
The problem isn’t the diagrams themselves. The fundamental problem is that most teams treat diagrams as an artifact. They draw the entire architecture in one or few diagrams, mixed with different levels and abstractions. But a diagram is a view. It’s one perspective of the system, generated for one audience at one moment in time to communicate context.
Diagramming on its own is no longer the default. Diagramming needs to be connected to a model. The systems, components, dependencies, and data flows all live inside the model. A diagram is an output of that model, generated for a specific purpose. Update the model, and every diagram drawing from it stays current.
Think of it like infrastructure as code. You don’t manually configure a VPC in the AWS console for every environment (i.e., prod and staging). You define it in Terraform, and the infrastructure is an output of that definition. This definition is version-controlled and easily replicated to multiple environments.
Architecture should work the same way. Define the model, version-control it, and generate diagrams as outputs.
When diagrams are outputs of a shared model, you solve the consistency problem by default. There’s no split-brain situation where diagrams show inconsistent data flows or services that might have been drawn by different architects from different teams. This level of consistency is even more critical, the larger the organisation and the more distributed the teams are.
New way of diagramming
We established the notion that diagrams are only outputs of an architecture. These outputs are generated from a source of truth we define as the model. The new way of diagramming is modifying the model (e.g., adding new services or dependencies, updating data flows) and having the diagrams update automatically. There are three ways to update the model: 1) manually through the UI, 2) programmatically via API/SDK, or 3) using AI agents.
For option (2), IcePanel exposes a REST API and SDKs that let you update the model programmatically. You can define a CI/CD pipeline in a git repository where every change to the model gets reflected in the overall architecture (and subsequently all its diagrams).
For option (3), IcePanel exposes an MCP server that allows AI tools like Claude or Cursor to perform read/write operations to the model. Architects can then query their models using AI agents, review suggestions, and document decisions through ADRs. Queries can range from simple questions like “how many services do we have?” to “what is the impact of migrating the payments API and what services depend on it”.
IcePanel Drafts using AI agents
With the new way of diagramming, we see a powerful workflow combining AI agents with IcePanel Drafts. Drafts are a way to explore changes to the architecture without impacting the live model. Think of it like pull requests for your architecture. You create drafts from the main model, propose changes in isolation, and merge them back once reviewed and approved.
Combined with AI, this powerful workflow looks like this: an AI agent opens a draft, proposes architectural changes based on a product spec, and submits it for human review. Architects review the draft the same way they’d review a PR and leave comments for the agent to address. Once the draft is merged, the live model gets updated, and every diagram generated from it reflects the change automatically.
The model is the kernel
In IcePanel, we treat the model as the kernel of software architecture. Every object, connection, and relationship lives in the model. Diagrams are views generated from it rather than drawn independently.
One of our core features is the model viewer. It is a live view of everything in your architecture (objects and connections). When a change is made to the model, whether through the UI or an API call, the model viewer reflects it immediately. This kernel can be version-controlled in a git repository, modified by agentic workflows, and reviewed by architects. This is a better version of architecture diagrams, dynamic.
To learn more, check out https://docs.icepanel.io/core-features/model-viewer
Conclusion
The old way of drawing architecture diagrams is dead. Manual, disconnected diagrams that go stale within weeks don’t serve architects, engineers, or the AI agents that increasingly need to reason about our systems.
Architecture isn’t going anywhere. But the way we document it has to change. Engineering teams are hesitant to rely on outdated, inconsistent diagrams and have less incentive to maintain them. However, a centralised workspace with a core data model solves this. It keeps diagrams consistent and integrates with the AI tools teams already use. This version of architecture diagrams won’t be dead.
