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
Что это?Это агентный скилл, который превращает кодовую базу, документ по архитектуре или описание системы простыми словами в интерактивную панорамируемую canvas-диаграмму — один самодостаточный HTML-файл с фокусировкой по клику, переключателем тёмной и светлой темы и экспортом в PNG.
Это отдельное приложение или дополнение к моему кодинг-агенту?Это агентный скилл, а не отдельное приложение: ваш кодинг-агент создаёт небольшой файл данных «scene» с описанием плоскостей, полос, блоков и связей, а два встроенных скрипта (validate.js, build.js) вшивают его в фиксированный HTML-шаблон, получая итоговую диаграмму.
Нужно ли что-то помимо кодинг-агента, чтобы этим пользоваться?Лишь Node.js (18+) для скриптов build и validate; в сгенерированном HTML диаграммы нет зависимостей времени выполнения, кроме запроса к Google Fonts за шрифтом JetBrains Mono.
Какие подводные камни при установке стоит обходить?Устанавливайте только одним способом: если использовать сразу два из трёх методов, скилл окажется в двух местах, и агент может загрузить ту копию, которую найдёт первой.
Он работает только с Claude Code?Нет — установщик skills.sh поддерживает Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI и ещё около 70 агентов; собственный npm-установщик репозитория нацелен именно на Claude Code.
Как на деле вызвать скилл после установки?Просто опишите желаемое естественным языком, например «Преврати docs/architecture.md в исследуемую диаграмму» или «Нарисуй архитектуру этого кода как canvas, который можно панорамировать», — агент распознаёт такие запросы и вызывает скилл.
Что можно делать внутри сгенерированной диаграммы?Панорамировать и масштабировать щипком, кликать компоненты, чтобы приглушить остальное и прочитать описание, переключать тёмную и светлую тему клавишей t, экспортировать текущий вид в PNG с разрешением 2x.
Как диаграмма выглядит визуально?Компоненты разложены по горизонтальным полосам — архитектурным слоям, сложенным сверху вниз в причинном порядке, с цветовой кодировкой по плоскостям; пунктирные границы обозначают ваше собственное, а сплошные — вендоров, инфраструктуру и поверхности приложений.
Можно ли поделиться с кем-то конкретным видом диаграммы?Да, состояние панорамирования и зума живёт в хэше URL, так что можно отправить ссылку, открывающую просмотрщик ровно в том месте, которое вы хотите показать.
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