Better Diagrams

Architecture diagrams and flowcharts for coding agents. Automatic layout, clickable details, browser editing, and offline HTML and SVG exports.

Install

With Node.js 22.20 or later:

npx skills add ruohao1/better-diagrams --skill diagram-authoring -g

Select your agent, then ask it to use diagram-authoring. The skill includes its CLI. For direct terminal use: npm install -g @isqrd/better-diagrams.

Showcase

Full gallery, SVGs, and runnable examples →

Code example: API → database

Save this as my-diagram/diagram.json:

{
  "version": 2,
  "title": "Order storage",
  "purpose": "Show where orders are stored.",
  "audience": "Developers",
  "rootViewId": "overview",
  "nodes": {
    "api": { "label": "API", "summary": "Accepts orders.", "details": "Validates incoming orders." },
    "db": { "label": "Database", "summary": "Stores orders.", "details": "Persists accepted orders." }
  },
  "views": {
    "overview": {
      "type": "architecture", "title": "Order storage", "detailLevel": "Components",
      "nodeIds": ["api", "db"],
      "edges": [{ "id": "save", "source": "api", "target": "db", "kind": "data", "label": "Save order" }]
    }
  }
}

To add a component, define it in nodes, include its ID in the view's nodeIds, and connect it with an edge. Use kind: "call" for service calls and kind: "data" for storage access.

With the CLI installed, build and open diagram.html in your browser:

better-diagrams build my-diagram --out diagram.html

For live editing, run better-diagrams dev my-diagram.

Use cases

• Map a repository's services and dependencies, with code references in node details.
• Explain workflows with decisions, failures, and retry paths.
• Keep an overview readable and open component internals in a modal.

Usage guide · Source format · Changelog · Releases