Show HN: Yantra – Interactive step-by-step diagrams as one offline HTML file

Interactive, step-by-step diagrams and one-page answers, shipped as one offline HTML file.

Website · Docs · Playground · Examples · Changelog

Yantra is an open-source diagram tool that turns a short JSON description into an interactive architecture diagram, sequence diagram, flowchart, state machine, ER diagram, org chart or mind map, or into a one-page answer with charts. It lays the diagram out, routes the edges, checks the result with a validator and writes one HTML file that works offline, with a walkthrough readers can step through. Use it from the command line, from coding agents through MCP, from any AI chat through the browser playground, or from Python.

• No boxes to place. Layout, edge routing and label placement are automatic; there are no coordinates in the JSON.
• A story, not just a picture. Steps highlight the cards and edges involved, with a description for each, so a reader can follow a request, a process or a decision.
• Checked before anyone sees it. The validator reports broken references, overlaps, edges through cards and label collisions, each with a stable code an agent can fix.
• One file to share. The output makes no network requests: email it, attach it to a ticket or open it from a USB stick. SVG, PNG and Markdown exports are there too.

One JSON format covers these kinds of diagram. Each picture links to its example.

| Architecture and flow | Sequence | State machine | | ER and class diagrams | Trees and org charts | Mind maps | | Nested groups | Answer pages | Chart cards, dark theme |

Also: drill-down from an overview into detail diagrams, charts on answer pages, and modes (for example production against local). Open any of them in the playground from Load an example.

Yantra needs Node.js 20.19 or later (22.12 or later on Node 22).

npm i -g @niyankhadka/yantra      # the `yantra` command, with a prebuilt viewer
yantra new diagram.json           # a starter diagram (--page for an answer page)
yantra validate diagram.json      # schema, references, story and rendered geometry
yantra build diagram.json         # -> diagram.html, works offline

A first diagram, step by step: Install and your first diagram.

{
  "meta": { "title": "Checkout", "description": "How an order is paid and stored." },
  "nodes": [
    { "id": "web", "type": "client", "data": { "title": "Web app", "subtitle": "Customer checkout" } },
    { "id": "api", "type": "service", "data": { "title": "Orders API", "tech": "Go" } },
    { "id": "db", "type": "data", "data": { "title": "Orders DB", "tech": "PostgreSQL", "icon": "database" } }
  ],
  "edges": [
    { "id": "web-api", "source": "web", "target": "api", "label": "POST /orders" },
    { "id": "api-db", "source": "api", "target": "db", "label": "INSERT order" }
  ],
  "steps": [
    { "title": "Overview" },
    { "title": "Submit", "highlightNodes": ["web", "api"], "highlightEdges": ["web-api"] },
    { "title": "Persist", "highlightNodes": ["api", "db"], "highlightEdges": ["api-db"] }
  ]
}

Save it as checkout.json, then run yantra validate checkout.json and yantra build checkout.json. The rules, budgets and every validation code are in Authoring diagrams; answer pages are covered in Answer pages.

Coding agents (Claude Code, Cursor, Codex, Antigravity). One command adds the Yantra skill and MCP server to your project, so the agent can read your code and draw it:

npx @niyankhadka/yantra init          # the agents whose folders exist here, else Claude Code
npx @niyankhadka/yantra init --all    # Claude Code, Cursor, Codex and Antigravity

init writes only inside the project, never overwrites a file it did not write, merges MCP configs and is safe to run again (--dry-run shows what it would do). Guide: Diagrams from your codebase.

AI chats (Claude.ai, ChatGPT, Gemini and others). Nothing to install: open the playground, press Copy prompt for your chat and paste it into the chat. Paste the JSON it answers with back into the playground to validate it, see it and download it. The button follows the editor: with a diagram loaded it copies the diagram too, and with validation findings it asks the chat to fix them. Everything runs in your browser. Guide: Use with Claude.ai, ChatGPT and any chat.

Existing diagrams. yantra import reads Mermaid, PlantUML, draw.io / diagrams.net and Visio .vsdx files and validates the result. Guide: Import Mermaid, PlantUML, draw.io and Visio.

Python. Build payloads in Python and let the CLI validate and build them. Guide: Python SDK.

• Layouts: layered layout with orthogonal edge routing; trees, org charts, decision trees and mind maps; groups nested up to six levels; an optional manual layout.
• Diagram kinds: flow and architecture, sequence (lifeline) view of the same payload, state machines with fork / join and regions, ER and UML class diagrams, chart cards.
• Walkthroughs: scenarios with steps, autoplay, camera follow and a present mode; folding for big diagrams; drill-down into detail diagrams up to eight levels.
• Answer pages: the conclusion first, then blocks such as points, metrics, charts, compare, table, timeline, FAQ, checklist, gantt, matrix and embedded diagrams.
• Charts: bar, column, line, area, pie and donut charts, sparklines, gantt plans and 2x2 or risk heat-map matrices, drawn as inline SVG with no chart library.
• Sharing: one offline HTML file; SVG, PNG and Markdown exports; view state in the URL hash; light and dark themes; print styles; your own logo.
• Languages and accessibility: 18 interface languages, right-to-left layout for Arabic, Hebrew, Persian and Urdu, full keyboard control and contrast tests on the theme.
• For agents: a validator with stable codes, a CLI, an MCP server (stdio and Streamable HTTP), an agent skill and a Python SDK.

CLI reference #

From a clone without npm link, use node bin/yantra.js in place of yantra.

MCP server #

yantra mcp (or node mcp/server.js) speaks MCP over stdio; yantra init registers it for your agents. Tools: yantra_get_schema, yantra_list_examples, yantra_get_example, yantra_validate, yantra_build, yantra_export, yantra_import, yantra_import_mermaid and yantra_screenshot. File access is sandboxed to YANTRA_INPUT_ROOT and YANTRA_OUTPUT_ROOT (both default to the server's working directory).

yantra mcp --http serves the same tools over Streamable HTTP for clients that connect by URL, such as Claude.ai and ChatGPT connectors. You host it; see Remote MCP server. Manual setup for every agent and Claude Desktop: Coding agents.

Viewer keyboard shortcuts #

Press ? in a diagram to see the keys that work there.

The view state is mirrored in the URL hash, for example #level=payments&step=3&mode=dev&view=sequence&theme=dark, so a link reopens the same view.

examples/ holds 25 diagrams, 13 answer pages and 7 chart pages, plus import samples for Mermaid, PlantUML, draw.io and Visio. Every example validates with no warnings. yantra examples lists them and yantra examples oauth-login -o oauth.json copies one. Companies and data in the examples are fictional.

The reference pages are the files in docs/, so they match the release you are reading.

git clone https://github.com/niyankhadka/yantra.git
cd yantra
npm install
npm run dev          # viewer with every example at http://localhost:3000
npm test             # Node test suite
npm run dev:site     # website and playground at http://localhost:3001/

Python SDK tests: pip install -e python/, then python -m unittest discover -s python/tests. Setup, layout of the repository and the rules the tests enforce are in the contributing guide.

• Contributing guide : setup, tests and pull requests.
• Support : where to ask questions and report bugs.
• Security policy : report vulnerabilities privately.
• Code of conduct .

If Yantra is useful to you, you can buy me a coffee, star the repository, or keep the "Made with Yantra" badge in your diagrams (meta.watermark: false hides it).

MIT © niyankhadka. The licence covers the code; the Yantra name and logo are covered by the trademark policy.