The pitch is seductive: describe your system in code, run a command, and watch as pristine diagrams materialize while documentation writes itself. No more stale Confluence pages. No more “I’ll update that diagram later” lies. Architecture as Code (AaC) has become the rallying cry for teams drowning in technical debt and documentation drift. But beneath the surface of tools like Structurizr, D2, and the latest AI-powered generators, a more troubling pattern is emerging, one where the appearance of architectural clarity is actively undermining our ability to understand what we’re building.
The problem isn’t that these tools don’t work. They work too well. They give us exactly what we ask for, which is often precisely the problem.
The Tool Gold Rush: From C4 to AI Prompts
The current AaC landscape splits into three distinct tribes, each with its own gospel.
First, you have the structured modeling purists wielding Structurizr and the C4 model. They’ll tell you that architecture is about rigor, about defining software systems, containers, components, and code in a strict hierarchy. Their diagrams are consistent, their terminology precise. The catch? You’re essentially writing Java or Python to generate boxes and arrows, and the cognitive load shifts from drawing to modeling. One team described it as “trading Visio headaches for DSL debugging nightmares.”
Then come the diagram-as-code minimalists championing tools like D2, Mermaid, and PlantUML. Their philosophy is simpler: just describe the diagram in text, version control it, and render it anywhere. It’s seductively straightforward until your 500-line D2 file becomes a tangled mess of connections that no human can parse, and changing one component’s position requires 30 minutes of coordinate tweaking. The degradation of architectural discourse due to AI-generated content has made this worse, developers now paste AI-generated Mermaid diagrams they barely understand into pull requests, creating a veneer of documentation that collapses under scrutiny.
The third tribe is the AI generation evangelists, and this is where things get truly spicy. Tools like Lucid AI and the emerging crop of startups promise to “transform vague descriptions into structured diagrams.” One developer recently built revibe.codes to generate Mermaid architecture diagrams directly from codebases. Another project, pacta, takes a different approach: treat architecture as a versioned artifact with validation rules and historical trend analysis. The promise is automation at scale, why model when a machine can infer?
But here’s the uncomfortable truth these tools gloss over: architecture is not a diagram. A diagram is a projection of architecture, a chosen perspective on a complex system. When you automate the projection without understanding the underlying model, you get exactly what you’d expect, beautiful, consistent, utterly misleading pictures of systems that don’t exist.
The Automation Paradox: When Your Code Lies Better Than You Do
The most dangerous moment in AaC adoption comes when teams believe their generated diagrams are the architecture. I’ve watched this play out in multiple organizations. The risks of LLM-generated code on architectural integrity extend directly to diagrams, your CI pipeline validates that the diagram syntax is correct, but has no idea if it matches the actual running system.
Consider the team that used an automated tool to generate their microservices architecture diagram. The tool scanned their repository, found REST API calls between services, and drew elegant arrows showing dependencies. What it missed: three critical services had been bypassing the API gateway for months, communicating through a shared database that appeared nowhere in the code. The diagram was “correct” according to the source, but the architecture it depicted was pure fiction.
This is the automation trap: the more sophisticated your tooling, the more confidently you can produce wrong information. A hand-drawn diagram that’s slightly out of date is obviously suspicious. A code-generated diagram that updates on every commit carries an implicit authority that’s dangerously unearned.
The architectural failures from distributed team decisions become even more insidious when automation enters the picture. When each team owns a slice of the AaC codebase, they optimize their local diagrams while global constraints evaporate. The tool shows green checks for every component, but the composition is broken.
The MCP Server Revelation: Architecture as Queryable Data
A fascinating development from the DEV Community suggests a path forward, though not the one tool vendors are selling. The Archyl MCP server approach treats architecture as queryable data rather than static diagrams. Instead of generating pictures, it provides programmatic access to architectural knowledge that AI tools can reason about.
This reframes the entire problem. The goal isn’t prettier diagrams, it’s making architecture inspectable and actionable. When your AI assistant can ask “which services depend on the payment gateway?” and get an accurate, current answer, the diagram becomes secondary. The architecture lives as a knowledge graph, not a PNG.
One startup, gjalla.io, is taking this further with “live architecture docs” accessible via MCP. The founder’s claim is telling: auto-generated docs from Claude Code were “too high level.” The problem with AI generation isn’t the quality of the output, it’s the lack of grounding in operational reality. By making architecture a queryable interface rather than a generated artifact, you shift from documentation to discovery.
The Hard Limits: What Code Can’t Capture
Even the most sophisticated AaC tools hit a fundamental wall: architecture is a social construct. It exists in the minds of engineers, in the implicit contracts between teams, in the tribal knowledge of why that weird service exists. No amount of code can capture the reason a team chose Kafka over SQS, the political negotiations that led to splitting the monolith, or the fear that prevents anyone from touching the legacy billing system.
The critical design decisions in modular monolith API layers illustrate this perfectly. You can diagram the module boundaries perfectly, but the diagram won’t tell you that the “shared” API layer is actually a source of coupling so tight that teams can’t deploy independently. It won’t reveal that the architecture is quietly betraying SOLID principles because of how modern patterns have evolved.
This is where the AaC movement reveals its naivety. Tools can enforce syntax, validate rules, and generate visuals. They cannot encode intent, context, or consequence. When comparing architectural patterns, the debate isn’t about which boxes connect to which, it’s about which forces each pattern balances. Code is terrible at representing forces.
The Pragmatic Path: Code as Scaffold, Not Scripture
So where does this leave us? Should we abandon Architecture as Code entirely and return to whiteboards and PowerPoint? Hardly. The value of AaC isn’t automation, it’s traceability. When used correctly, these tools create a scaffold for architectural reasoning, not a replacement for it.
Here’s what actually works:
- 1. Use AaC for baseline documentation, not canonical truth. Let Structurizr generate your starting C4 diagrams, but treat them as conversation starters. The real work happens when engineers gather around the output and argue about what’s missing.
- 2. Automate validation, not generation. Tools like pacta shine when they validate that code matches architectural constraints, not when they draw pretty pictures. The GitHub Action that flags when a PR introduces an unauthorized dependency is worth a thousand auto-generated diagrams.
- 3. Make architecture interactive, not static. The MCP server approach, making architecture queryable by humans and AI alike, creates a living knowledge base. When an engineer can ask “show me the blast radius if this service fails” and get a real answer, you’ve achieved something valuable.
- 4. Version the decisions, not just the diagrams. Every architectural change should capture why in a commit message, ADR, or decision log. The diagram shows what changed, the decision record shows why it matters.
The pragmatic alternative of modular monoliths has taught us that architecture is about managing complexity, not eliminating it. AaC tools are no different. They don’t reduce the mental load of architecture, they shift it. The question is whether you’re shifting it to a place where it can be managed or just hidden.
The Uncomfortable Takeaway
The Architecture as Code movement is at a crossroads. Down one path lies a future where teams generate perfect diagrams of perfectly wrong systems, where real-world architectural failures are preceded by beautiful, automated documentation that captured none of the critical constraints.
Down the other path is a more humble vision: tools that make architecture visible and discussable, that expose rather than obscure complexity, that serve engineers rather than replacing their judgment.
The spicy truth? Your architecture diagrams are already code, they’re just code that runs in human brains. The moment you try to compile that mental model into a formal language, you discover all the undefined behavior, the implicit assumptions, the tribal knowledge that makes your system actually work. Automation doesn’t fix this, it amplifies it.
Choose your tools accordingly. And never trust a diagram you didn’t argue about first.
