draw-architecture README

The project's README from github.com/yulonghe97/draw-architecture. As one markdown file: README.md.

draw-architecture

npm license Agent Skills

An agent skill that turns any system architecture — a codebase, an architecture doc, or a plain-English description — into an interactive, explorable canvas diagram: monospaced, organized into colour-coded planes, with pan/zoom, click-to-isolate focus, a dark/light switcher, and PNG export. One self-contained HTML file, ready to share or publish.

▶ Try the live demo — pan around, zoom in, click any component to isolate it and read what it does.

Shoply e-commerce platform rendered as an architecture canvas

Install

Three ways in — pick one, since installing twice leaves you with the skill in two places and your agent loading whichever it finds first.

Method Command Best for
skills.sh npx skills add yulonghe97/draw-architecture Any of 70+ agents; managed updates
npm installer npx draw-architecture Claude Code, or a shared ~/.agents/skills
Manual git clone + symlink Reading or modifying the skill itself
skills.sh — works with any agent (recommended) 
npx skills add yulonghe97/draw-architecture

The skills CLI supports Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI, and 70-odd others. It asks which agents to install to and whether to symlink or copy, then records a lockfile so npx skills update can pull later versions.

Installs into the project (./.claude/skills/ for Claude Code) by default. For every project on the machine, add -g:

npx skills add yulonghe97/draw-architecture -g

Non-interactive, for CI or dotfiles:

npx skills add yulonghe97/draw-architecture --skill architecture-canvas -g -a claude-code -y

Remove it again with npx skills remove architecture-canvas. The directory page is at skills.sh/yulonghe97/draw-architecture.

npm installer — this repo's own 
npx draw-architecture

Asks where to put the skill: your Claude Code skills directory (~/.claude/skills), a shared ~/.agents/skills directory symlinked into Claude Code, the current project (./.claude/skills), or a path you name. Pass --global, --agents, --project, or --dir <path> to skip the question.

It refuses to overwrite or delete any directory it can't positively identify as this skill, and records a marker file so upgrades and npx draw-architecture uninstall know what they're touching.

Manual — clone and symlink

The skill is just this repo's contents, so a symlink is enough:

git clone https://github.com/yulonghe97/draw-architecture.git
ln -s "$(pwd)/draw-architecture" ~/.claude/skills/architecture-canvas

Use this if you want to edit the template or the layout rules and have your changes take effect immediately.

Requirements: Node.js, for the build and validate scripts. The generated HTML has no dependencies beyond a Google Fonts request for JetBrains Mono.

[!NOTE] The npm package is draw-architecture; the skill it installs is architecture-canvas — that's the name your agent matches against, and the directory name on disk.

Use it

Restart your agent so it picks up the new skill, then just describe what you want. It triggers on requests like:

  • "Create an interactive architecture canvas for our platform — here's how it works: …"
  • "Turn docs/architecture.md into an explorable diagram"
  • "Map this codebase's architecture as a canvas I can pan around"

What you get

Every diagram is a single index.html with a full viewer built in:

And a consistent visual language that makes every diagram read the same way:

Meridian ML platform — closed retraining loop routed through the side gutter

Click any box to isolate it and see what it does:

Click-to-isolate focus mode with readout panel

How it works

The skill never writes viewer code. The entire viewer ships as a fixed template (assets/template.html); the agent authors only a scene — pure data describing planes, bands, boxes, and edges — and two small scripts do the rest:

understand the architecture → write scene.js → validate → build → (publish)

Because outputs share one template, every diagram you generate looks like it came from the same design system — the model can't drift on typography, palette, or interaction design, only on content.

Try it without an agent

The live demo is this repo's example, published as-is. Or open examples/shoply-canvas.html in a browser locally — it's the canvas from the first screenshot, built from examples/shoply-scene.js, which doubles as the canonical example of the scene format. To rebuild it yourself:

node scripts/build.js --scene examples/shoply-scene.js --out /tmp/demo/index.html \
  --title "Shoply — platform architecture" \
  --kicker "SHOPLY — PLATFORM ARCHITECTURE" \
  --sub "<b>browse</b> → <b>price</b> → <b>order</b> → <b>fulfil</b> → <b>learn</b>" \
  --slug shoply-architecture

The scene format

A scene is ~250 lines of declarative data — nine constants (W, H, PLANES, BANDS, BOXES, EDGES, TEXTS, SWATCHES, CHIPS) in world coordinates. The full data model, layout recipe (band stacking math, text baselines, gutter routing), and design guidance live in references/scene-format.md.

{ id: 'orchestrator', plane: 'domain', band: 'band-domain',
  x: 590, y: 770, w: 440, h: 110, r: 10,
  dash: true,                     // dashed = an abstraction you own
  name: 'Order Orchestrator',
  about: 'Runs checkout as a saga — with compensations on failure.',
  texts: [ ['bl', 614, 798, 'Order Orchestrator'],
           ['bs', 614, 820, 'saga-based checkout: cart → payment → fulfilment'],
           ['bn', 614, 858, 'every state change published to Kafka'] ] }

Publishing

The skill can optionally hand the finished folder to the artifact.cafe skill to publish a no-login review URL reviewers can comment on. Any static host works too — the output is just a folder with an index.html.

Repository layout

SKILL.md                     the skill definition the agent follows
bin/cli.js                   the `npx draw-architecture` installer
assets/template.html         the complete viewer (scene injected at build time)
scripts/build.js             scene + template → index.html
scripts/validate.js          layout linter for scenes
references/scene-format.md   data model + layout recipe
examples/shoply-scene.js     canonical example scene (fictional e-commerce platform)
examples/shoply-canvas.html  the built demo — open in a browser
evals/evals.json             test prompts + assertions used to develop the skill

Contributing

Issues and pull requests are welcome. If you're changing the viewer or the layout rules:

  1. Edit assets/template.html (the viewer) or scripts/validate.js (the linter) — never the built example directly.

  2. Run the validator and rebuild the example so the two stay in sync:

    node scripts/validate.js examples/shoply-scene.js
node scripts/build.js --scene examples/shoply-scene.js --out examples/shoply-canvas.html \
  --title "Shoply — platform architecture" \
  --kicker "SHOPLY — PLATFORM ARCHITECTURE" \
  --sub "<b>browse</b> → <b>price</b> → <b>order</b> → <b>fulfil</b> → <b>learn</b>" \
  --slug shoply-architecture

  3. Open examples/shoply-canvas.html in a browser and check the change.

Changes to the skill's behaviour belong in SKILL.md or references/scene-format.md; evals/evals.json holds the prompts used to test them.

License

MIT

draw-architecture (yulonghe97/draw-architecture)

Searching Database…

147 ·GitHub
Draw-architecture
What is this?This is an agent skill that turns a codebase, architecture doc, or plain-English description of a system into an interactive, pannable canvas diagram — a single self-contained HTML file with click-to-isolate focus, a dark/light switcher, and PNG export.
Is this a standalone app or does it plug into my coding agent?It's an agent skill, not a standalone app: your coding agent authors a small 'scene' data file describing planes, bands, boxes and edges, and two built-in scripts (validate.js, build.js) splice that into a fixed HTML template to produce the final diagram.
Do I need anything besides my coding agent to use it?Just Node.js (18+) for the build and validate scripts; the generated diagram HTML has no runtime dependencies beyond a Google Fonts request for JetBrains Mono.
Any install pitfalls I should avoid?Install it only one way — using two of the three methods at once leaves the skill in two places, and your agent may end up loading whichever copy it finds first.
Does it only work with Claude Code?No — the skills.sh installer supports Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI and roughly 70 other agents; the repo's own npm installer is aimed specifically at Claude Code.
How do I actually trigger the skill once installed?Just describe what you want in natural language, e.g. 'Turn docs/architecture.md into an explorable diagram' or 'Map this codebase's architecture as a canvas I can pan around' — the agent recognizes requests like these and invokes the skill.
What can I do inside the generated diagram?Pan and pinch-zoom, click any component to dim everything else and read a description, flip dark/light mode with the 't' key, and export the current view as a 2x-resolution PNG.
How is the diagram laid out visually?Components sit in horizontal bands by architectural layer stacked top-to-bottom in causal order, colour-coded by plane, with dashed borders marking things you own and solid borders for vendors, infra and app surfaces.
Can I share a specific view of a diagram with someone?Yes, the pan/zoom state lives in the URL hash, so you can send a link that opens the viewer at the exact spot you want them to see.
What are similar projects?archify, drawio-skill, reladraw, svg-diagram, visual-explainer, geo-sleuth, oh-my-mermaid, live-panel-skill
Which topics is it in?architecture-diagram, png, diagrams, gemini-cli, github-copilot, architecture, opencode, visualization, skill, cursor, html, agent-skills
Creator
yulonghe97
Size
0.5 MB
Stars
147
Updated
CommitAug 25
Age
2mo
Commits · 90 Days