Show HN: Yantra – Interactive step-by-step diagrams as one offline HTML file Yantra, an open-source diagram tool from developer Niyankhadka, converts a short JSON description into interactive architecture diagrams, sequence diagrams, flowcharts, state machines, ER diagrams, org charts or mind maps and writes a single HTML file that works offline with no network requests. The tool lays out nodes and routes edges automatically with no coordinates in the JSON, runs a validator that reports broken references, overlaps, edges through cards and label collisions with stable codes an agent can fix, and is usable from the command line, from coding agents via an MCP server, from a browser playground or from Python; it requires Node.js 20.19 or later (22.12 or later on Node 22) and installs via npm as @niyankhadka/yantra or via pip as niyankhadka-yantra. Interactive, step-by-step diagrams and one-page answers, shipped as one offline HTML file. Website https://yantra.nbk.com.np/ · Docs https://yantra.nbk.com.np/docs/ · Playground https://yantra.nbk.com.np/playground/ · Examples https://github.com/niyankhadka/yantra/tree/main/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 https://yantra.nbk.com.np/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 | Without installing | Python | Set up your coding agent | |---|---|---| | npx @niyankhadka/yantra build diagram.json | pip install niyankhadka-yantra | npx @niyankhadka/yantra init | A first diagram, step by step: Install and your first diagram https://yantra.nbk.com.np/docs/guides/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 https://yantra.nbk.com.np/docs/authoring/ ; answer pages are covered in Answer pages https://yantra.nbk.com.np/docs/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 https://yantra.nbk.com.np/docs/guides/coding-agents/ . AI chats Claude.ai, ChatGPT, Gemini and others . Nothing to install: open the playground https://yantra.nbk.com.np/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 https://yantra.nbk.com.np/docs/guides/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 https://yantra.nbk.com.np/docs/guides/import/ . Python. Build payloads in Python and let the CLI validate and build them. Guide: Python SDK https://yantra.nbk.com.np/docs/guides/python/ . - 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 | Command | What it does | |---|---| | yantra validate