Archyne — a visual editor for Mermaid diagrams

A draw.io-style diagram editor with two-way sync to Mermaid code. Edit visually
(drag-and-drop, connect, rename) or edit the Mermaid text — each side updates the
other. Because the document is standard Mermaid, LLMs can generate, read, and
modify your diagrams as plain text, and anything they produce opens on the canvas.

Runs entirely on your own machine — in a browser, as a desktop app, or inside
VS Code. No server, no accounts, nothing leaves it. Self-host by serving the
dist/ folder from any static file server.

Try it

Open the live demo → — it is the same
static build, running in your browser. Nothing is uploaded.

Or run it locally, with no clone and no build:

npx archyne                 # opens http://localhost:4173
npx archyne diagram.mmd     # …with a diagram already loaded

Or inside the editor you already have open:

code --install-extension naxeris.archyne

Archyne registers as an optional editor for .mmd, so the file stays VS Code's
— its dirty dot, its undo, its save, its diff against HEAD. A
```mermaid block inside Markdown gets an Open on canvas action above the
fence, which is where most Mermaid actually lives: the diagram is edited in
place, and the rest of the document is left alone. It is on the
Marketplace
and on Open VSX, for
VSCodium, Cursor, Windsurf, Gitpod and Theia.

Desktop builds for Windows, macOS and Linux are attached to every
release. They are not
yet code-signed — Windows warns, macOS needs one xattr command — and each
release page says so; the web version and npx archyne avoid the question
entirely.

Architecture diagrams with 16 000+ searchable vendor icons

Sequence diagrams — drag participants to reorder

The screenshots are generated from the real app by
node scripts/screenshots.mjs, so they cannot quietly go stale.

Run

npm install
npm run dev            # development, http://localhost:5173
npm run build          # production build into dist/ (static, any web server)
npm start              # serve the build locally (same as npx archyne)
npm test               # round-trip parser/serializer tests
npm run mcp            # MCP server (stdio) for LLM agents
npm run mcp:smoke      # end-to-end MCP server test
npm run desktop        # desktop app (Electron shell around the build)
npm run desktop:build  # Windows installer (NSIS) into release/

There is no backend: the web build is static files, the desktop app is the
same build in an Electron window, and diagrams live in your files. Opening a
.mmd file with the desktop app loads it directly (the installer registers
the file association), and Save writes back to that same file — as it does
in the browser too, on engines with the File System Access API. Elsewhere,
Save falls back to a download.

Diagram families Archyne has no visual editor for — gantt, pie, mindmap
and friends — still open, rendered read-only, with the Mermaid code fully
editable and the file untouched on save.

Importing files that are not Mermaid

Import… (in the overflow menu) takes seven other formats and converts each
into the Mermaid diagram it most nearly is. It is deliberately not the same
action as Open: opening a file means editing it and saving it back, and an
import is never written back.

Every conversion is shown before it lands. The importer runs, and what it
produced is put up in a preview — the diagram drawn by Mermaid's own renderer,
what kind it became, how many elements and connections came across, and every
caveat that applies: pages skipped, elements with no equivalent, a drawing
that looked like a different sort of diagram. The preview opens on a read-only Archyne
canvas — the same components the editor draws with, so it is what you will
get, with zoom and pan — and two buttons switch to Mermaid's own rendering
and to the generated source. Where a source can be read more than one way —
PlantUML could be three things, draw.io two — Read as lets you overrule
the detection and see the other reading before deciding. Cancel costs nothing, because nothing has been
placed yet. An import is lossy by construction, and the moment to find that
out is before it has replaced what you were looking at. The original file is never touched: an import arrives
unbound from its source, so Save is Save-as into a new .mmd and nothing is
overwritten with Mermaid its own tool could not read back. Whatever could not
come across is counted rather than passed over in silence.

Graphviz DOT

.dot and .gv, directed or not, strict or not. Nodes, edges, shapes,
colours, rankdir, edge labels and line styles, and cluster_* subgraphs as
containers — DOT describes a graph rather than a drawing, so there is very
little that has no counterpart. Plain subgraphs stay invisible, as they are in
Graphviz. A file with no coordinates is laid out with ELK; one that has been
through dot -Tdot keeps the positions it was given.

The point is the DOT nobody writes by hand. terraform graph, go mod graph,
doxygen, dbt and most build tools emit it, and it is usually squinted at in
whichever viewer is nearest:

terraform graph > graph.dot   # then open graph.dot

Node ids are named after the labels, so what you get is source worth reading
rather than n1 --> n2.

draw.io

.drawio (and the .xml older versions write). What comes across is the part
that was drawn: the boxes and their text, the shape each one is, its colours,
the connections and their labels and line styles, the containers, and where
everything sat — the geometry lands in the %% graph:positions comment, so
an imported diagram opens looking like the one you left rather than
re-laid-out from scratch. Hand-routed corners come too.

It is a migration, not a mirror. draw.io is a free-form geometry editor and
Mermaid is not, so rotation, layers, per-shape fonts and the thousands of
stencils have no equivalent and do not survive; Mermaid's fourteen vertex
shapes are matched as closely as they can be, and anything unrecognised
becomes a rectangle. A file with several pages converts the first, and you
are told so.

SQL DDL

A schema is already an ER diagram, written down as CREATE TABLE. Tables
become entities, columns become typed attributes, and a foreign key becomes a
relationship whose cardinality is read off the constraints rather than
guessed: the child end is many unless the column is unique, the parent end is
optional when the column is nullable, and the line is solid — identifying —
only when the key is part of the child's own primary key.

Dialect-agnostic and deliberately shallow: it reads the statements that
describe shape and steps over views, triggers, grants, indexes and
partitioning, which is what lets a whole pg_dump be opened rather than a
hand-trimmed excerpt. Constraints added afterwards with ALTER TABLE — how a
dump always writes them — count the same as inline ones.

PlantUML

Sequence diagrams only. PlantUML is a dozen languages sharing a pair of
@start/@end markers, and the sequence grammar is the one that lines up
with Mermaid closely enough to convert without guessing. A class, state or
component diagram is refused by name rather than half-converted into
something you would have to check line by line.

Within sequence diagrams: participants and their kind, messages and arrow
styles, activation (including the ++ shorthand), notes, and the
alt/else/opt/loop/par/break/critical blocks. Not carried:
skinparam and colours, the preprocessor, box participant grouping,
dividers and delays.

Which diagram you get

The three text formats say what they are, so the family is read off the file
rather than fixed: a PlantUML class keyword produces a Mermaid class
diagram, [*] --> produces a state diagram, and a DOT file drawn entirely
with record labels produces a class diagram instead of boxes full of pipe
characters.

The four drawing formats do not say. draw.io, Visio, Excalidraw and
Lucidchart all put every kind of diagram on the same canvas, so a sequence
diagram there is lifeline shapes rather than a sequence diagram. Those
import as flowcharts — but draw.io is checked for the tell-tale styles, and a
drawing that looks like a sequence, ER or class diagram says so on import
rather than leaving you to work out why it came across as boxes. Excalidraw
has no semantic types at all, so there is nothing to read; Lucid's files are
read as the flowcharts a .lucid so nearly always is.

Visio and Excalidraw

Visio .vsdx is read out of its package: shapes with their text, the shape
each master suggests, literal colours, the <Connects> table as edges, and
the page geometry — centres in inches from the bottom of the sheet, turned
into corners in pixels from the top. Containers, layers, themes and the
sub-shapes of a group are not attempted; a Visio group is one composite
stencil far more often than a logical container, so it arrives as the single
shape it looks like.

Excalidraw scenes give up their boxes, ellipses and diamonds with the text
bound to them, the arrows their bindings name, frames as containers, and the
positions. Freehand strokes, images and loose text have no counterpart and
are counted out.

Lucidchart

A .lucid file is a zip holding a document.json — the interchange format
Lucid documents for its own import. The document on its own is accepted too:
it is the same thing, unzipped. What comes across is what the file can say:
the boxes and their text, the shape each one is (Lucid's library matched as
closely as Mermaid's fourteen allow), the colours somebody actually chose,
the connections and their labels and line styles, hand-routed corners as
waypoints, and the geometry — whose co-ordinates are the canvas's own, so the
layout survives as %% graph:positions without any turning over. A file with
several pages offers them in the preview, and the reader picks which one comes
across.

Not carried: rotation, opacity and image fills have no Mermaid counterpart,
and Lucid's invisible hotspots are counted out. Lucid groups are
selection-grouping — they make items move and resize together, which is not
what a Mermaid subgraph is — so a group's members arrive as the free shapes
they look like. Containers have no list of their members in the file, so each
arrives as the box it looks like rather than as an empty subgraph.

Windows note: if desktop:build fails with EPERM … rename win-unpacked,
your project sits in a Defender-protected folder (e.g. Documents). Build
with the output elsewhere:
npx electron-builder --win -c.directories.output=%LOCALAPPDATA%\archyne-release

Embedding Archyne in another app

Load the app with ?embed=1 inside an iframe and talk to it over
postMessage. In embed mode Archyne never touches localStorage — the host
owns the data.

The bridge is default-deny: you must name your origin with
&origin=https://your.app, and diagram content is only ever posted back to an
origin on that list. Comma-separate several if you need to. origin=* accepts
any parent frame and is for local development only.

<iframe id="mf" src="https://archyne.your.host/?embed=1&origin=https://your.app"></iframe>
<script>
  const MF = "https://archyne.your.host";
  const mf = document.getElementById("mf").contentWindow;
  window.addEventListener("message", (e) => {
    if (e.origin !== MF) return; // verify the sender, too
    if (e.data.type === "ready")
      mf.postMessage({ type: "load", code: "flowchart TD\n a-->b" }, MF);
    if (e.data.type === "change") save(e.data.code); // live edits, debounced
    if (e.data.type === "exported") show(e.data.dataUrl); // png/svg data URL
  });
  // on demand:
  mf.postMessage({ type: "getCode" }, MF); // → { type:"code", code }
  // format: "png" | "svg" | "pdf"
  mf.postMessage({ type: "export", options: { format: "png", background: "light" } }, MF);
</script>

Messages from the editor: ready, loaded, change {code}, code {code},
exported {format, dataUrl}, error {message}. A working example ships at
/embed-demo.html.

MCP server — let agents edit your diagrams

mcp/server.ts exposes the diagrams as MCP tools, so Claude Code (or any MCP
client) can work with them directly. The included .mcp.json registers it
automatically when you open this project in Claude Code; elsewhere:

claude mcp add archyne -- npx tsx mcp/server.ts

Writes are safe by construction: invalid code never touches disk, paths can't
escape the root, and if an agent rewrites a diagram without the
%% graph:positions and %% graph:waypoints lines, the previous manual
layout is carried over for the nodes and edges that still exist — an LLM
restructuring your diagram won't scramble your hand-arranged layout.

Live co-editing. A file open in the editor is watched, so an agent's write
lands on the canvas within a couple of seconds without a reload. A document
with unsaved changes is never overwritten: you are told the file moved and
your work stays, with Reload from disk in the overflow menu when you want
the other version.

How it works

• Canvas → code: structural edits (add/delete/connect/rename/reshape) regenerate
  the Mermaid text; dragging a node only rewrites the positions comment, leaving the
  rest of your text untouched.

• Code → canvas: the text is parsed with mermaid's own parser, so anything
  mermaid accepts renders on the canvas. Parse errors are shown without destroying
  the last good canvas state.

• Layout lives in trailing comments the rest of the world ignores — node
  positions and sizes in one, the corners of hand-routed edges in another:

  %% graph:positions {"start":{"x":0,"y":0},"db":{"x":40,"y":300,"w":220,"h":90}}
  %% graph:waypoints {"start>check":[[120,80]]}
  

  So the file stays a 100% valid Mermaid diagram (GitHub, Notion, LLMs, mermaid-cli
  all render it), while your manual layout survives save/reload/LLM-edit cycles.
  Diagrams without a positions line are auto-laid-out with ELK. Edges are keyed
  by their endpoints rather than by index, so inserting a line above one does
  not move its corners onto a different connection.

Current scope

Seven Mermaid diagram families, all with visual editing and two-way sync.
Anything else Mermaid can draw — gantt, pie, mindmap, timeline — opens
read-only, rendered rather than refused.

• Flowcharts — all 14 vertex shapes, all edge stroke/arrow types,
  subgraphs as groups (create/dissolve from the toolbar), and full
  classDef/style round-trip with color pickers in the inspector.
• State diagrams (stateDiagram-v2) — states, start/end pseudo-states,
  transitions with labels, composite states as groups (nested transitions
  round-trip correctly).
• ER diagrams — entities with typed attributes/keys/comments, crow's-foot
  cardinalities, identifying vs non-identifying relationships.
• Class diagrams — fields and methods (with abstract/static classifiers),
  «interface» annotations, generics, namespaces as groups, sticky notes,
  inheritance/composition/aggregation/dependency markers, cardinalities,
  dotted relations.
• Sequence diagrams — participants/actors as draggable columns with
  lifelines (drag horizontally to reorder), messages as ordered horizontal
  arrows with all eight operators; drag a message by its grab strip to
  reorder it, into or out of a block, or step it from the inspector. Notes and
  loop/alt/opt blocks are created from the palette (drop them at a row),
  renamed and deleted in place; par/critical/break blocks, activations, and
  autonumber are rendered and fully preserved through any canvas edit.
• Architecture diagrams (architecture-beta) — cloud/solution
  architecture with vendor icons — Microsoft's own 636 Azure
  architecture icons are bundled (azure:virtual-networks, and the
  catalogue codes other tools write resolve too), alongside the Iconify
  logos, devicon, carbon, tabler and simple-icons collections:
  more than 16 000 icons, all searchable from the palette, nested groups for
  VPCs/subnets, junctions, and side-anchored connections with per-end arrows. A vendor's own set — Azure's, AWS's —
  can be imported as SVGs, from files or from a pasted link; the desktop
  build takes a whole .zip. Any of Iconify's ~200 000 icons can be pulled in
  the same way (api.iconify.design/mdi/database.svg). Imported icons are
  sanitised, kept for the browser, and travel inside the .mmd that uses
  them — so the file draws correctly for somebody who has neither the pack
  nor a network.
• C4 models (C4Context/C4Container/C4Component) — persons,
  systems, containers, components (with _Ext/db/queue variants),
  enterprise/system/container boundaries as groups, relations with
  technology labels and bidirectional arrows. The original C4 flavor and
  title round-trip.

The palette, inspector, and "New…" menu adapt to the active diagram kind.
Plus: undo/redo (Ctrl+Z/Y — the code being the source of truth makes
history a stack of snapshots), copy/paste (Ctrl+C/V, id-remapped, edges
included), resizing with drag handles or typed width and height,
snap-to-grid, alignment guides while dragging, double-click any node or
edge to rename it, drag-and-drop, direction switch, ELK auto-layout,
.mmd open/save, PNG/SVG/PDF export of the canvas — to a file, or
straight to the clipboard to paste into a document — copy code, localStorage
autosave, live Mermaid preview tab.

The source panel behaves like an editor: drag its edge to give the code
more room (or the canvas more, and the width is remembered), Ctrl+= and
Ctrl+- set the type size — Ctrl+wheel and the A−/A+ buttons do the same,
and Ctrl+0 goes back — and Shift+Alt+F formats the document, which
re-indents blocks and tidies blank lines without touching what any line says.
The %% graph:… comments the app writes for itself start folded into a
single line naming what they hold; they are still in the file, and one click
opens them.

The PDF is a single page, either cut to the diagram or centred on A4 or
Letter, turned landscape when the diagram is wider than it is tall. It
carries the diagram as a losslessly compressed image at the chosen quality
rather than as vector paths — 3× is 288 dpi, which prints cleanly, and SVG
remains the export for artwork that has to scale without limit.

For reviewers and buyers

Archyne is local-first by construction: no backend, no accounts, no
telemetry, and nothing it needs to fetch — Mermaid's renderers and the icon
collections all ship in the build. Your diagrams never leave the machine.

One request can go out, and only when you ask for it by name: importing an
icon from a link you pasted. connect-src in the Content Security Policy
names the five hosts that makes possible and nothing else — never
* — and a test fails if that list and the code disagree.

Untrusted diagram text is held by two independent layers — Mermaid's
sanitizer and the CSP — each verified separately in a real browser on every
pull request. Accessibility is checked the same way: axe reports no WCAG
2.2 AA violations across seventeen interface surfaces, in both themes.

Two things stated up front rather than discovered later: the desktop
installers are not yet code-signed, and the accessibility work is a
self-assessment rather than a signed VPAT. A fuller security architecture
note and a criterion-by-criterion conformance report exist and can be shared
on request.

License

MIT — for Archyne's own code. Third-party dependency licenses are
listed in THIRD-PARTY-NOTICES.md; all are compatible
with MIT distribution (elkjs is EPL-2.0, consumed unmodified as a library;
the Iconify collections are CC0/MIT/Apache-2.0, with depicted logos remaining
their owners' trademarks). The full breakdown is also available in-app, under
About Archyne in the ⋯ menu.

One bundled thing is not MIT. The 636 Azure architecture icons in
src/icons-azure.generated.json are Microsoft's, shipped under
their terms, which
permit use in architectural diagrams, training materials and documentation.
Archyne's MIT grant does not extend to them. NOTICE states the
terms in full — read it before redistributing a build.

Trademarks

Archyne is an independent project. It is not affiliated with, endorsed by,
or sponsored by Mermaid, Mermaid Chart, or Microsoft. Microsoft, Azure and
the Azure icons are trademarks of the Microsoft group of companies, used here
only to identify the icons they publish.

"Mermaid" is a trademark of its respective owner. It appears here and in the
interface only to describe the file format Archyne reads and writes — the
kind of use that identifies compatibility, not origin. The Mermaid library
itself is used under its MIT licence,
which grants rights over the code and none over the name.

Vendor logos in the bundled icon collections likewise remain trademarks of
their respective owners.