Technical diagrams that live in your repository. Architecture, workflow, sequence, data-flow and lifecycle diagrams as JSON you can read in a diff, edit by hand or through an agent, and send to anyone as a single offline HTML file.
No account. No server. The editor, the CLI and the exports all run on your machine.
Light theme: hero-light.png · how these were captured: docs/media/capture.json
npx mapgrain@0.2.5 validate diagram.json # is it a real document?
npx mapgrain@0.2.5 layout diagram.json # ELK writes the coordinates
npx mapgrain@0.2.5 view diagram.json -o diagram.htmldiagram.html opens with no server and no network: search, pan, zoom, follow a path, switch
theme. Send it as a file.
To edit by hand instead, run the editor from a checkout:
pnpm install
pnpm --filter @mapgrain/editor devPick a template, or start blank. Rename with Enter, connect two cards, drag an endpoint onto
a different card, choose a line shape, arrange with ELK, walk through it step by step, or run a
workflow by firing its transitions.
Each kind has its own vocabulary, its own validation, and its own layout.
| Kind | For | Nodes | Connections |
|---|---|---|---|
architecture |
what the parts are and what calls what | service, datastore, queue, gateway, actor, system, job, external | calls, reads, writes, publishes, subscribes, depends-on |
workflow |
who does what, in what order, with branches | actor, job, decision, system, gateway | calls, outcome |
sequence |
messages between parties over time | participant, actor | message, reply |
data-flow |
where data comes from and where it rests | process, datastore, entity, external | data, reads, writes |
lifecycle |
the states one thing moves through | state | transition |
A worked example of each ships with the agent skill: workflow, sequence, data-flow, lifecycle, architecture. Every one validates, lays out and exports — that is a test, not a claim.
npx mapgrain@0.2.5 <command> diagram.json| Command | Does |
|---|---|
validate |
checks the document against the schema and the kind's own rules |
layout |
runs ELK and writes layout.positions; --rearrange to start over |
view |
writes the offline HTML viewer |
export |
--format svg | png | json |
diagnose |
geometry warnings as JSON; --strict to fail on them |
compare |
what changed between two revisions, optionally as Before/Delta/After HTML |
watch |
re-reads a file as an agent writes it, keeping the last valid version |
studio |
serves one opened file on loopback for a local editor session |
doctor |
reports runtime, assets, worker, renderer and output |
Those frames are CLI receipts, not a live agent prompt: install paths are tested, live prompt runs are not.
Mapgrain ships a skill so an agent writes the JSON and the CLI checks it, instead of the agent guessing pixel coordinates.
npx skills add ensp1re/mapgrain --skill mapgrain --yes --agent claude-codeCursor, Codex, OpenCode, GitHub Copilot, Gemini CLI, Grok and Windsurf are covered too — the matrix is in docs/agents.md, and the skill itself is skills/mapgrain/SKILL.md.
docs/FEATURES.md has the full table with status per row. Not shipped:
hosted sharing, Mermaid and draw.io import, and live agent prompt runs. Historical
npx mapgrain@0.1.0 still rejects sequence, data-flow and lifecycle documents.
Issues and pull requests are welcome. CONTRIBUTING.md covers setup, the checks, and what a good pull request looks like; CODE_OF_CONDUCT.md covers conduct; SECURITY.md covers reporting a vulnerability.
pnpm install
pnpm verify # lint, typecheck, unit tests, queue validationNode 24 LTS in CI, Node 26 accepted locally. pnpm 10 for this repository — end users only need
npx. Longer walkthrough: docs/getting-started.md. Package layout
and invariants: docs/ARCHITECTURE.md.
MIT. See LICENSE.