DiagramOS — Making Mermaid Diagrams Actually Usable

Mermaid is great — until you need to actually collaborate on it. You paste a diagram in a PR review, your PM opens it and sees gibberish. You send the preview image, someone asks you to change a label, and you're back to wrestling with text. Meanwhile, visual editors like Lucidchart and draw.io produce bloated, proprietary formats that no dev wants in their codebase. I was tired of living in that gap. So I built DiagramOS. ## The problem nobody talks about Mermaid has an adoption problem. Devs love it — you write code, you get diagrams, it lives in your repo. But the moment a non-dev needs to touch it, you've lost them. The syntax is not intuitive for anyone who doesn't think in DSLs. And even for devs, trying to manually position nodes, debug why an arrow is going the wrong direction, or figure out why your flowchart looks like spaghetti — it's a nightmare. Visual editors solve the UX but destroy the output. You can't check Lucidchart XML into Git. You can't review it in a PR. It's not portable. It's a black box. The moment you leave the tool, you're stuck. What I wanted was both: drag nodes, see clean Mermaid code. Edit the code, see the canvas update. And have an AI in the loop to help with both. That's DiagramOS. ## The insight: LLMs as a sync bridge The hard part of building a bidirectional Mermaid editor is sync. If you drag a node in the canvas, you need to update the Mermaid code. If you edit the code, you need to update the canvas. These are two very different representations of the same data, and keeping them in sync is not trivial. The naive approach is to write a parser. Parse the Mermaid AST, track node positions in a separate data structure, merge on save. I started down this path and immediately hit edge cases. Mermaid's syntax is flexible in ways that make parsing painful. Subgraphs, different diagram types, styling directives — it's a mess to parse reliably. Then I had a different idea: what if I use a fast LLM for the translation layer? Not a slow, expensive one. Claude Haiku or Gemini Flash — models that respond in under a second. When you make a change in the canvas, I serialize the React Flow state and ask the LLM to emit valid Mermaid. When you edit the code, the LLM generates the React Flow node/edge structure. It's probabilistic, not deterministic, but in practice it works remarkably well. ```typescript // Canvas → Mermaid sync async function syncCanvasToMermaid(nodes: Node[], edges: Edge[]): Promise { const canvasState = serializeFlowState(nodes, edges); const response = await llm.invoke({ model: 'claude-haiku', // Fast, cheap, good enough prompt: `Convert this React Flow graph to valid Mermaid: ${JSON.stringify(canvasState, null, 2)} Return ONLY the Mermaid code, no explanation.` }); return response.content; } ``` The key insight is that you don't need 100% fidelity. You need 95% fidelity at 100ms latency, not 100% fidelity at 2s latency. Diagrams don't have to be pixel-perfect round-trips. Close enough, fast enough, is the right tradeoff here. ## Building the thing The stack: Next.js 15 (App Router), React Flow for the canvas, Monaco Editor for the code pane, Mermaid.js for parsing and rendering previews, Zustand for state, shadcn/ui for components, DynamoDB for persistence. React Flow was the right call for the canvas. It gives you nodes, edges, drag-and-drop, selection, and a solid plugin ecosystem out of the box. I built on top of it with bezier curved edges (Miro-style, not the default sharp ones), node resize handles, edge labels, and a formatting toolbar. The toolbar feels like FigJam — you can change node shapes, colors, add borders, all without touching code. One feature I'm genuinely proud of: comment nodes. Sticky notes on the canvas. They don't affect the Mermaid output — they're stored separately in DynamoDB and overlaid on the canvas. This sounds trivial but it matters a lot for collaboration. You can annotate a diagram without polluting the actual diagram code. Your "TODO: clarify this flow" note lives next to the node, not in a comment in the code that gets lost. ### The AI chat panel There's a side panel where you can chat with an AI about your diagram. You can say "add a step between the auth check and the redirect" and it'll update both the canvas and the Mermaid code. The model picker supports Gemini Flash (fast, cheap, good for simple edits), Claude Sonnet via Bedrock (better reasoning, design suggestions), and Claude Opus for complex architectural diagrams. The chat maintains context of the current diagram state. It's not just a generic "generate Mermaid" prompt — it knows your current nodes, edges, and the last few edits. So "make it cleaner" actually means something because it can see what you have. ## The MCP server DiagramOS ships with an MCP (Model Context Protocol) server. This means you can use DiagramOS as a tool inside Cursor, Claude Desktop, or any MCP-compatible AI client. Your AI coding assistant can read and write diagrams in your DiagramOS workspace directly. The protocol is JSON-RPC 2.0 over stdio. The server exposes tools like get_diagram, update_diagram, list_diagrams, create_diagram. So when you're in Cursor and ask it to document your API flow, it can spin up a diagram in DiagramOS instead of dumping ASCII art in a comment. This is the kind of integration that makes tools feel like they belong in a real workflow. ## What's next The dashboard already has diagram cards with previews — you can see all your diagrams at a glance. Next up: real-time collaboration (multiplayer cursors, conflict resolution), diagram version history, and Git integration so you can auto-commit Mermaid files to your repo on save. The repo is open source. Go break it, fork it, send a PR. I'm building this because I want to use it, and I think the right thing to do with tools like this is open-source them. GitHub: https://github.com/fl-satyakam/diagramos