{
  "markdown": "<p align=\"center\">\n  <img src=\"https://em-content.zobj.net/source/apple/391/triangular-ruler_1f4d0.png\" width=\"120\" />\n</p>\n\n<h1 align=\"center\">Diagrammer</h1>\n\n<p align=\"center\">\n  <strong>tell the model, get the diagram</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://diagrammer.idra.app\"><img src=\"https://img.shields.io/badge/live-diagrammer.idra.app-0a84ff?style=flat\" alt=\"Live\"></a>\n  <a href=\"https://github.com/IdraDev/diagrammer/stargazers\"><img src=\"https://img.shields.io/github/stars/IdraDev/diagrammer?style=flat&color=yellow\" alt=\"Stars\"></a>\n  <a href=\"https://github.com/IdraDev/diagrammer/commits/main\"><img src=\"https://img.shields.io/github/last-commit/IdraDev/diagrammer?style=flat\" alt=\"Last Commit\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/github/license/IdraDev/diagrammer?style=flat\" alt=\"License\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#why\">Why</a> •\n  <a href=\"#map-types\">Map Types</a> •\n  <a href=\"#install\">Install</a> •\n  <a href=\"#authoring-skill\">Skill</a> •\n  <a href=\"#schema\">Schema</a> •\n  <a href=\"#er-diagrams\">ER</a>\n</p>\n\n---\n\nA local-first, schema-driven viewer for **LLM-authored diagrams**. Hand a model the [authoring skill](./skills/diagrammer/SKILL.md), it returns a JSON document, and the viewer renders it on a pannable, zoomable canvas — **mindmap, tree, flowchart, graph, ER diagram, concept map, or timeline**, auto-laid-out per type. No account. No cloud. No drag-pixels-by-hand.\n\n## Why\n\nI never found a **truly open-source, zero vendor lock-in** way to take a mind map or technical diagram and just _view it_. Every option pulled me into a SaaS account, a proprietary file format, a paywalled export, or a dialect of someone else's DSL. So Diagrammer: one tiny JSON schema, a static viewer that runs in your browser, no backend, no signup, no lock-in. Your data stays your data — paste it, drop it, export it, host the whole thing yourself in a `dist/` folder.\n\n## Map Types\n\n**Pick by `type`. Layout is automatic.**\n\n<table>\n<tr>\n<td width=\"25%\">\n\n#### 🧠 mindmap\n\n> Branches radiate from one central topic. Brainstorm, outline, taxonomy of ideas.\n\n</td>\n<td width=\"25%\">\n\n#### 🌳 tree\n\n> Strict hierarchy. Org chart, file tree, taxonomy with one parent per child.\n\n</td>\n<td width=\"25%\">\n\n#### 🔀 flowchart\n\n> Directed process w/ decision diamonds. Pipelines, state machines, runbooks.\n\n</td>\n<td width=\"25%\">\n\n#### 🕸️ graph\n\n> Arbitrary network: deps, citations, **ER diagrams**, knowledge graphs.\n\n</td>\n</tr>\n<tr>\n<td>\n\n#### 💡 concept\n\n> Concept map w/ labelled, often bidirectional links. Reinforcing ideas, not hierarchies.\n\n</td>\n<td>\n\n#### 📅 timeline\n\n> Linear sequence of events. Roadmaps, history, milestones.\n\n</td>\n<td colspan=\"2\">\n\n#### 🗄️ ER (as `graph`)\n\n> Entities = `shape: \"rectangle\"` + bold label + attributes in `description` w/ `(PK)`/`(FK)` markers. Edges carry verb + cardinality (`places (1—N)`).\n\n</td>\n</tr>\n</table>\n\n- **No coordinates** — auto-layout per `type`. Drag if you must, viewer writes positions back.\n- **Local-first** — recents in `localStorage`, paste/drop JSON, no upload.\n- **Edit mode** — drag nodes, connect handles, double-click rename, side panel for shape/color/emphasis/edge style.\n- **Examples** — one of every layout type, including ER, in the in-app menu.\n- **Theme** — light, dark, system. Light by default.\n\n## Install\n\n### Web viewer\n\n```bash\ncd web\nbun install\nbun run dev\n```\n\nOpen [http://localhost:5173](http://localhost:5173).\n\n**Build:** `cd web && bun run build` → static `web/dist/`. Drop on any host.\n\n**Live:** [diagrammer.idra.app](https://diagrammer.idra.app).\n\n### Skill (Cursor / Windsurf / Cline / Codex / Claude Code / Gemini)\n\nDrop the Diagrammer authoring skill into your editor of choice:\n\n```bash\n# macOS / Linux / WSL / Git Bash\nbash install.sh --all          # install every supported agent\nbash install.sh --only cursor  # just one\nbash install.sh                # autodetect from your $PWD\n\n# Windows (PowerShell)\n./install.ps1 -All\n./install.ps1 -Only cursor\n./install.ps1\n```\n\n| Agent       | Lands in                                               |\n| ----------- | ------------------------------------------------------ |\n| Cursor      | `.cursor/rules/diagrammer.mdc`                         |\n| Windsurf    | `.windsurf/rules/diagrammer.md`                        |\n| Cline       | `.clinerules/diagrammer.md`                            |\n| Codex       | `.codex/{config.toml,hooks.json}`                      |\n| Claude Code | `.claude-plugin/{plugin,marketplace}.json`             |\n| Gemini CLI  | `gemini-extension.json`                                |\n| Generic     | `AGENTS.md` (any agent that reads `AGENTS.md` at root) |\n\nAll variants reference the canonical [`skills/diagrammer/SKILL.md`](./skills/diagrammer/SKILL.md). For ChatGPT / Copilot Chat / any web UI without a skill format, paste `skills/diagrammer/SKILL.md` into the system prompt or custom instructions.\n\n### Stack\n\n| Layer      | Tool                              |\n| ---------- | --------------------------------- |\n| Bundler    | Vite                              |\n| UI         | React 19 + TypeScript             |\n| Styling    | Tailwind CSS v4                   |\n| Primitives | Radix UI in shadcn-style wrappers |\n| Canvas     | React Flow (`@xyflow/react`)      |\n| Compiler   | React Compiler                    |\n\n## Authoring Skill\n\n[`skills/diagrammer/SKILL.md`](./skills/diagrammer/SKILL.md) is the contract LLMs follow to produce diagrams this viewer can render. It documents the schema, when to use each `type` (incl. ER), visual conventions, worked examples, and anti-patterns.\n\nThe home page exposes a **Copy authoring skill** button — paste it into your model's system prompt, a Claude Code skill file, a Cursor rule, or any other instruction surface.\n\n```\n\"Make me an ER for an order-management DB\" → JSON → drop on canvas → done.\n```\n\n## Schema\n\n```json\n{\n  \"version\": \"1\",\n  \"type\": \"mindmap\",\n  \"title\": \"Untitled\",\n  \"description\": \"Optional one-liner\",\n  \"nodes\": [\n    { \"id\": \"root\", \"label\": \"Center\", \"emphasis\": \"strong\" },\n    { \"id\": \"a\", \"label\": \"Branch A\", \"color\": \"blue\" }\n  ],\n  \"edges\": [{ \"from\": \"root\", \"to\": \"a\", \"label\": \"optional\" }]\n}\n```\n\n| Field               | Type  | Notes                                                                          |\n| ------------------- | ----- | ------------------------------------------------------------------------------ |\n| `version`           | `\"1\"` | Schema version. Always `\"1\"`.                                                  |\n| `type`              | enum  | `mindmap` · `tree` · `flowchart` · `graph` · `concept` · `timeline`.           |\n| `nodes[].shape`     | enum  | `rectangle` · `rounded` · `ellipse` · `diamond` · `hexagon` · `pill`.          |\n| `nodes[].color`     | enum  | `default` · `slate` · `blue` · `green` · `amber` · `rose` · `violet` · `cyan`. |\n| `nodes[].emphasis`  | enum  | `normal` · `strong` · `subtle`.                                                |\n| `edges[].style`     | enum  | `solid` · `dashed` · `dotted`.                                                 |\n| `edges[].direction` | enum  | `forward` · `backward` · `both` · `none`.                                      |\n\nFull reference: [`skills/diagrammer/SKILL.md`](./skills/diagrammer/SKILL.md).\n\n## ER Diagrams\n\nER diagrams render as `type: \"graph\"`. The schema covers the common case without dedicated attribute lists:\n\n| Concept       | Convention                                                                                    |\n| ------------- | --------------------------------------------------------------------------------------------- |\n| Entity        | `shape: \"rectangle\"`, `label: \"**Name**\"`, `description: \"id (PK), col1, col2_id (FK), ...\"`. |\n| Primary       | `color: \"blue\"` + `emphasis: \"strong\"`.                                                       |\n| Lookup / weak | `color: \"slate\"` + `emphasis: \"subtle\"`.                                                      |\n| Relationship  | edge with `label: \"verb (1—N)\"`, `direction: \"both\"`.                                         |\n| Chen-style    | Intermediate `shape: \"diamond\"` node when relationship has its own attributes.                |\n| Cardinality   | Pick one: `1—1` / `1—N` / `M—N` (or `0..N` / `1..*`). Stay consistent.                        |\n\nWorked ER example shipped in the in-app **Examples** menu (`Order management ER`).\n\n## Examples\n\nIn-app **Examples** menu carries one of each layout type:\n\n- 🧠 **Launching a SaaS** — mindmap with workstream branches\n- 🌳 **Web platform** — tree of HTML, CSS, JS, Web APIs\n- 🔀 **Pull request lifecycle** — flowchart w/ CI and review branches\n- 🗄️ **Order management ER** — entity–relationship diagram w/ cardinalities\n- 💡 **Functional programming** — concept map w/ bidirectional links\n- 📅 **Web platform milestones** — timeline 1991 → today\n\nDrop any `*.json` from [`web/examples/`](./web/examples) onto the canvas, or paste straight from clipboard.\n\n> [!IMPORTANT]\n> **No persistent storage / no backend — for now.** Diagrammer currently has\n> zero server-side persistence. Everything (recents, prefs, the active map)\n> lives in your browser's `localStorage`. Clear the site data, lose the maps.\n> **Export your maps if you care.**\n>\n> Persistent storage (cloud sync / accounts / shared workspaces) is planned\n> but **not the next milestone**. The current focus is hardening the viewer +\n> authoring schema first; persistence will land once the foundations are\n> solid. Until then, treat Diagrammer as a stateless renderer over JSON files\n> you own.\n\n## Roadmap\n\nIn rough order of what I'm working on:\n\n1. **Now** — polish the schema, layouts, edit-mode UX, and authoring skill.\n   Multi-group canvas, edge markers, ER conventions, better packing.\n2. **Next** — additional map types and finer-grained per-group styling\n   (background, label, collapse).\n3. **Later** — optional persistent storage backend (self-hostable). No\n   account walls, no proprietary format. Stays opt-in; the local-first JSON\n   workflow remains the default.\n\nIf you want a feature pulled forward, open an issue.\n\n## 🛠️ Contributing\n\nRead [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a PR. TL;DR: local-first stays local-first, the schema is a public contract, [`skills/diagrammer/SKILL.md`](./skills/diagrammer/SKILL.md) and [`web/src/lib/skill.ts`](./web/src/lib/skill.ts) move together, and `bun run lint` + `bun run build` must pass.\n\n## Star This Repo\n\nIf Diagrammer save you mass clicking — leave mass star. ⭐\n\n[![Star History Chart](https://api.star-history.com/chart?repos=idraDev/Diagrammer&type=date&logscale&legend=top-left)](https://www.star-history.com/?repos=idraDev%2FDiagrammer&type=date&logscale=&legend=top-left)\n\n## License\n\nMIT — by **IdraDev**. Free like a blank canvas.\n",
  "bytes": 10845,
  "sha": "cdf1857e82489a1cd0c3e9f9b6f6e67c911eb3a8a142fbc30f994371256ca907",
  "repo_slug": "idradev/diagrammer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_idradev_diagrammer_acbb4c83/readme"
}