OpenFlowKit: a local-first diagram studio that treats Mermaid as a first-class input

The gap OpenFlowKit aims at: structured diagrams without a hosted account

Most diagramming tools force a choice. Freeform whiteboards give you a canvas but no diagram grammar, so a flowchart is just shapes that happen to be arranged in a row. Code-only tools give you a grammar but no canvas, which means every layout adjustment is a text edit and a re-render. Hosted products give you both and keep the file on their servers. OpenFlowKit's README frames the project as refusing that trade, and the specific claim it makes is narrow enough to check: it is the combination of a visual canvas, bidirectional diagram-as-code, AI generation across ten providers, automatic icon assignment from a library of more than 1,600 technology icons, anchored auto-layout, WebCodecs-based MP4 export, and an MCP server, all under MIT with no server-side storage. The audience is developers who already produce architecture diagrams as a side effect of their work: the person who has a Mermaid block in a README, an AWS account diagram that keeps going stale, or a design doc that needs a walkthrough video. That person does not want a new SaaS subscription, and does not want to hand-draw boxes either.

Mermaid import and icon assignment: the mechanism that carries the pitch

The README's worked example is the clearest description of how the tool behaves. You paste a Mermaid flowchart, and OpenFlowKit renders it on the visual canvas while assigning branded icons to technology nodes automatically. The README gives this input:

flowchart TD API[Express API] --> DB[(PostgreSQL)] DB --> Cache[Redis Cache] Cache --> Queue[RabbitMQ]

According to the README, that produces the Express wordmark, the PostgreSQL elephant, the Redis logo, and the RabbitMQ icon, all auto-detected. The README states that eight Mermaid diagram families are supported: flowchart, architecture, state, class, ER, sequence, mindmap, and journey. This is a real design decision, not a cosmetic one. Icon assignment means the tool has to map node labels to an icon catalogue, which is a heuristic and will misclassify unusual or abbreviated labels. The README does not describe how ambiguous labels are resolved, and that is the first place I would expect friction in practice. The upside is that a pasted Mermaid block stops looking like a text render and starts looking like something you would put in a slide, without you touching a single node.

Diagram as code with bidirectional sync, and why that is the hard part

The feature table lists bidirectional diagram-as-code with a git-friendly DSL, and separately lists Mermaid import. Those are two different capabilities, and the README is careful enough to present them as such. Import is one-directional: text in, canvas out. Bidirectional sync means an edit on the canvas writes back to the DSL, and an edit to the DSL updates the canvas. That round trip is where most tools quietly give up, because a hand-placed node position has no natural representation in a text grammar unless the grammar carries layout metadata. OpenFlowKit's answer to this is anchored layout: you pin nodes, and auto-layout rearranges the rest around the pins. Read together, these two features suggest the intended workflow is to let ELK do the bulk arrangement, pin the handful of nodes whose position carries meaning, and let the DSL remain the source of truth. The README also mentions a self-correcting AI loop, where generated DSL that fails is shown back to the model so it can repair its own output. That is a sensible design for a text-generating step, since malformed DSL is the predictable failure mode, though the README does not say how many repair attempts occur or what happens when repair fails.

Ten providers, one of them local: the AI surface and its honest boundary

AI generation is listed with ten providers, including a local Ollama preset described as fully offline diagramming. The distinction matters more than the count. A hosted provider means your architecture description leaves the machine, which for many teams defeats the point of a local-first tool. The Ollama preset is the configuration that keeps the whole loop on localhost, and it is the one worth evaluating if data residency is your reason for looking at this project at all. The README does not name the other nine providers, so I cannot tell you which ones are covered. It also does not state model size requirements for the Ollama path, and diagram DSL generation is a task where small local models tend to produce syntactically plausible but structurally wrong output. The self-correcting loop is presumably aimed at exactly that, but whether a given local model is good enough is something the README does not answer. Treat the ten-provider claim as a breadth statement, and the Ollama preset as the one that changes the threat model.

Running it: the app, the repo, and the MCP server

The README points at a hosted instance at app.openflowkit.com, documentation at docs.openflowkit.com, and the source at github.com/Vrun-design/openflowkit on the main branch. The stack is React 19, TypeScript 5, and Vite 6, per the badges, with a CI workflow at .github/workflows/quality.yml. The README does not include install or build commands, so I am not going to invent a package manager invocation that may not match the repository. If you want to self-host, the first thing to read is package.json and the Vite config in the repository, not this article. The other integration path is the MCP server, which the README says lets Claude Desktop, Cursor, and Windsurf drive the tool directly. It describes this as a first-party server but does not give the command to start it or the config block to paste into a client. That is a documentation gap worth weighing: MCP client configuration is where most people get stuck, and the README leaves it to the docs site. The layout engine runs in a web worker, which the README presents as keeping the UI responsive while ELK computes. That is a concrete architectural choice and it is the right one for a browser tool with a heavy graph algorithm inside it.

MP4 export via WebCodecs, and the browser dependency nobody mentions

Cinematic MP4 export is described as hardware-encoded H.264 through WebCodecs, with faster-than-realtime rendering. If that works as stated, it is a genuine differentiator: producing a walkthrough video of an architecture diagram normally means screen recording, which is slow, resolution-dependent, and captures your cursor. Rendering frames directly and encoding them in the browser removes that step. The constraint is the API surface. WebCodecs is not uniformly available across browsers, and the README does not state which browsers are supported or what happens on a browser without it. Since this is a browser application, that is a hard dependency rather than a graceful degradation, and it is the kind of thing that should be checked before you build a workflow around it. The same applies to Figma export, which the README describes as editable SVG. Editable SVG is a meaningfully different promise from a flat image export, but the README does not describe how node grouping and text styling survive the trip.

Where OpenFlowKit is the wrong tool, and what to use instead

The README's own comparison table is the most useful part of the document because it names the alternatives. Against Excalidraw and tldraw, the stated difference is that those are freeform whiteboards with no structured diagram types, no DSL, and no code imports. That cuts both ways. If your actual need is a shared whiteboard for a workshop, where people scribble and move things around freely, OpenFlowKit's structured model and auto-layout will fight you. Excalidraw is the better fit there, and the difference is not quality but intent: freeform canvas versus diagram grammar. Against Mermaid.js, the stated difference is that Mermaid is code-only with no visual canvas and no interactive editor. If your diagrams live in Markdown files and are rendered by your documentation pipeline, adding a browser application to the loop is a regression in workflow, not an improvement. Mermaid is the right answer for that case, and OpenFlowKit's value only appears when you need to edit visually or produce something a text renderer cannot. Against PlantUML, the README notes server-dependent rendering. If you are already running PlantUML in CI, replacing it means replacing a text-in, image-out pipeline with a stateful application. The one comparison I would treat with more caution is the Draw.io row, which the README characterizes as decade-old UX with limited AI integration. Draw.io's desktop build is also local and also free, and its file format is widely supported by other tools. OpenFlowKit's advantage over it is the AI path and the MCP server, not local-first operation, which Draw.io already had.

Licence, maintenance, and what to check before you commit

The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. This is not legal advice; read the LICENSE file in the repository for the operative text. The practical implication of MIT here is that you can fork and self-host without a commercial conversation, which is the main reason a team would pick this over a hosted product. On maintenance, the repository shows a last push of 2026-08-19 and no retrieved releases, so there is no tagged version history to reason about. That means you should pin to a commit rather than expect a versioned artifact, and you should expect the main branch to move. The CI workflow at .github/workflows/quality.yml is the signal to check for whether the build is actually gated. There is no release cadence to plan upgrades around, so the upgrade cost is whatever it costs to diff main against your fork. If you are self-hosting for a team, that is an ongoing commitment rather than a one-time install. The verification list before adoption is short and specific: confirm the MCP server starts and connects in your client of choice, confirm the Ollama preset works against a model you have pulled locally, and confirm that a diagram you edit on the canvas survives a round trip through the DSL without losing your pinned node positions.

Editorial conclusion

Adopt OpenFlowKit if you want diagrams that never leave your machine, if your source material is already Mermaid, or if you want an agent to write and repair diagram DSL through the MCP server. Do not adopt it if you need real-time multi-user editing or a hosted service with an SLA, because the README describes zero server-side storage and no account system. Before committing, verify the MCP server setup against your client, confirm the Ollama preset points at a model you have actually pulled, and check whether the diagram-as-code round trip preserves the layout you hand-tuned.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Vrun-design/openflowkit on GitHub