Architecture diagrams don’t go stale because nobody cares. They rot because updating them is a separate, tedious chore from the actual work of building software.
That’s the uncomfortable truth the Mermaid fanbase doesn’t want to hear. Making diagrams text-based and versionable was supposed to fix documentation drift forever. It didn’t. It just made the rot more visible, and easier to blame on your teammates’ laziness.
The emergence of bidirectional editing tools, though, is quietly changing the calculus. And the teams paying attention are the ones who’ll stop treating their architecture docs like museum exhibits.
The Mermaid Promise That Never Quite Landed
Mermaid convinced a generation of developers that diagrams could live alongside code. The format sits in your repo, shows up in pull request diffs, and integrates with the tools you already use. The Mermaid.js project even markets itself as allowing “non-programmers to easily create detailed diagrams.”
That’s technically true. It’s also beside the point.
The core problem isn’t the diagramming syntax. It’s that someone still has to write the thing. And writing a diagram after your code is done feels like doing homework. The text-as-diagram revolution lowered the barrier to entry, sure. But it created an entire generation of architectures documented by a single, heroic engineer who got excited about the tool in week one and abandoned it by week three.
Why static, hand-drawn diagrams become misleading over time is well-documented territory, but Mermaid diagrams suffer the exact same fate, just with nicer pull request previews.
The Real Problem: Mermaid Is Still One-Way
Here’s the uncomfortable specificity: Mermaid gives you a great one-way street. You write text, it renders an image. The diagram follows your words. But the actual system you’re building doesn’t care about your words. It cares about the code.
When your code changes and your diagram doesn’t, you’ve created a lie that’s now version-controlled, reviewable, and searchable. That’s not progress. That’s a more efficient way to mislead your future self.
JetBrains’ official Mermaid plugin for IntelliJ IDEA and other IDEs gives you editing support and a diagram preview, but it’s still fundamentally a source-to-render pipeline. The reviews tell the story: one user wrote that the plugin “only highlights the content written in Mermaid and does not show a preview”, while another complains about the lack of zoom support. Version 263.5153.40 shipped in September 2026 with absolutely zero update notes. The tooling is stagnant because the concept, Mermaid as a living document, hasn’t evolved.
And how architecture diagrams decay into irrelevance when disconnected from code does exactly that the moment your team hits a deadline.
What Bidirectional Editing Actually Changes
The architectural drift problem isn’t that diagrams are hard to write. It’s that they’re disconnected from the moment of change. Bidirectional editing attacks that disconnection directly.
Tools like the embeddable Mermaid editor from JointJS+ turn the diagram from a static render into an interactive surface. You edit the flowchart source in the code panel and the diagram updates instantly. But the reverse also works: you click a node, drag it, rename it directly on the canvas, tweak its shape and fill through a context toolbar, and the Mermaid source rewrites itself to match.
The demo also supports clicking nodes to highlight their source mentions, and moving your caret through the code scrolls the diagram to follow. That’s not a novelty, it’s a debugger for your documentation.
The source is available on GitHub for anyone who wants to embed this pattern directly into their own applications. The features list reads like a checklist of what developers actually need: built-in shapes, content-driven shapes, context toolbar, validation, zoom & pan, and export to SVG.
This isn’t a standalone tool play. It’s a blueprint for embedding visual flowchart editing into whatever product or workflow already exists.
The Obsidian Angle: Why Your Notes App Might Solve What Your IDE Won’t
The most interesting experiment in this space isn’t happening in polished enterprise tooling. It’s happening inside Obsidian, and it’s called Mermaid Flow.
Developed by Mohammed Thanseer, this plugin has racked up 4,000 downloads in four months and takes a genuinely different approach. It gives you a drag-and-drop canvas where you move nodes and draw connections without touching Mermaid syntax at all. The plugin writes the underlying code for you.
What makes this notable: your edits “round-trip safely.” The plugin reads existing Mermaid blocks, lets you edit them visually, and writes them back without destroying custom syntax like click, classDef, or linkStyle directives. Those advanced elements are preserved verbatim, which means your diagram’s intent survives the visual editing process.
Mermaid Flow also handles persistent layouts, manual node positions get saved in hidden Mermaid comments, so your arrangement survives reloads and the diagram still renders normally in standard Mermaid viewers. It works across Reading mode, Live Preview, and Source mode, with mobile-friendly touch gestures and nested subgraph support.
There’s even an optional AI assist feature that generates a flowchart from a text prompt using your own provider, OpenAI, Gemini, Anthropic, or a local CLI.
The accessibility angle matters here. The plugin’s docs explicitly say “no Mermaid syntax required.” That’s a direct challenge to the assumption that architecture diagrams must be written by developers who enjoy DSLs.
Where This Still Falls Short
Let’s be clear-eyed about what bidirectional editing doesn’t fix.
First, it doesn’t connect your diagram to your actual codebase. A bidirectional Mermaid editor syncs between source text and visual canvas. It doesn’t sync between your diagram and your Kubernetes manifests, your OpenAPI specs, or your database schema. That next layer, the pitfalls of assuming code-generated diagrams solve architectural drift, remains untouched.
Second, most of these tools focus on flowcharts specifically. The Obsidian plugin’s roadmap lists sequence, mindmap, and ER visual editors as MVP versions. Richer sequence fragments, loops, alts, and activations are still “next.” The most useful architecture diagrams, the ones showing system context, container relationships, and deployment topology, are structurally more complex than flowcharts.
Third, teams don’t adopt tools because they’re technically elegant. They adopt them because they reduce friction in the moment. A diagram editor that requires you to open Obsidian, use a plugin, and click “Edit” still represents a context switch. The friction is lower, but it’s not zero.
That’s precisely why the embeddable approach in the JointJS+ demo is architecturally interesting. It suggests a future where diagram editing lives inside your IDE, your issue tracker, or even your pull request interface, anywhere developers already are.
The Enterprise Reality Check
Every one of these features exists in a vacuum. The hard problem is organizational.
The limitations of traditional diagramming standards like UML and how C4 attempted to fix them show a familiar pattern: a standard gets adopted with enthusiasm, then abandoned when maintenance costs exceed perceived value. Between 2004 and 2011 everybody might have been reading about UML, but almost nobody was doing proper UML documentation on real projects.
Mermaid has better staying power because it’s lower ceremony. It doesn’t require certification. It doesn’t demand enterprise architects. It just requires someone to type a few lines of text.
But low ceremony cuts both ways. Bidirectional editing doesn’t actually require a specific tool. The fundamental requirement is the same as what living documentation has always needed: a team culture where diagramming is part of the definition of done, not an afterthought performed when the folks from the architecture review board come knocking.
The Bottom Line on Bidirectional Editing
The pitch that Mermaid diagrams alone will save your architecture documentation fails for the same reason every static artifact fails: it’s a snapshot of a moment, not a system responding to change.
Bidirectional editing, whether through embedded editors, Obsidian plugins, or IDE integrations, doesn’t magically fix architecture drift. What it does is remove one specific excuse: “I meant to update the diagram but I didn’t have time to redraw it.”
When you can double-click a node, change its name, and have the Mermaid source update itself, the cost of keeping documentation fresh drops from “redesign the whole diagram” to “make the change you were already making.”
Moving beyond static tools like DrawIO toward version-controlled, code-integrated practices was chapter one. Break the static-copy mindset and you’re in chapter two: diagrams that act as interactive, editable surfaces rather than frozen output files.
The tools are getting good enough that “I didn’t have time” is no longer credible. The next excuse, whether your team keeps using it, is entirely on you.
