Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
docs: streamline README content
tt-a1ie42eb34dc3b8
diff --git a/README.md b/README.mdindex 4912ed9e..6758f6da 100644--- a/README.md+++ b/README.md@@ -49,399 +49,220 @@ The Export menu — Copy PNG to clipboard plus 4 download formats (all raster ex-Live example: [`examples/web-app.html`](examples/web-app.html) — open in a browser, press <kbd>T</kbd> to toggle theme, <kbd>E</kbd> to open Export. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.+Example file: [`examples/web-app.html`](examples/web-app.html). Download or clone the repository, open the file locally, then press <kbd>T</kbd> to toggle themes or <kbd>E</kbd> to open Export.-## Diagram types--Archify now has five primary outputs:--| Type | Good for | How to ask |-|---|---|---|-| **Architecture** | System components, cloud resources, databases, caches, services, boundaries, security groups | Describe the system structure |-| **Workflow** | Request lifecycles, approval flows, tool calls, CI/CD, runbooks, incident response | Describe participants, step order, and key branches |-| **Sequence** | API call chains, request lifecycles, cache fallback, auth checks, async trace, service interactions | Describe who calls whom, in what order, and what returns |-| **Data Flow** | Data pipelines, ETL/ELT, analytics events, PII isolation, warehouse sync, lineage, downstream consumers | Describe sources, processing stages, storage, sensitivity boundaries, and consumers |-| **Lifecycle** | State machines, order/task/deployment/agent-run lifecycles, wait states, retries, cancellation, timeout, terminal states | Describe states, transition events, retry paths, and terminal outcomes |--Architecture diagrams explain system structure — components, boundaries, and how they connect:--```text-Use archify to draw an architecture diagram:-React frontend calls a Node.js API backed by PostgreSQL and Redis, deployed on AWS behind CloudFront.-```--Sample SaaS diagram: [`examples/web-app.html`](examples/web-app.html).--Real-repo examples (renderer-backed JSON IR):--- [`examples/archify-repo.html`](examples/archify-repo.html) — this project's skill → JSON IR → renderers pipeline-- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — same pipeline with `layout.mode: "grid"` (`row`/`col` placement)-- [`examples/maka-architecture.html`](examples/maka-architecture.html) — third-party desktop agent workbench (Maka)+## Quick start-Workflow is not trying to replace every general-purpose flowchart. It is a technical communication diagram: swimlanes, semantic colors, a clear happy path, and secondary async / approval / trace paths.+### 1. Install-```text-Use archify to draw a workflow:-User submits a request -> Agent plans -> Approval Gate if needed -> Tool Call -> Trace Log -> Final Reply+```bash+npx skills add tt-a1i/archify -g```-Open the example here: [`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html).--+This installs Archify for supported agents through the open-source [`skills` CLI](https://github.com/vercel-labs/skills).-Sequence diagrams explain a narrower interaction over time:+To try it without a permanent install:-```text-Use archify to draw a sequence diagram:-User opens a page, the frontend calls the API, the API verifies JWT, reads Redis, falls back to Postgres on cache miss, returns JSON, and emits trace.+```bash+npx skills use tt-a1i/archify@archify --agent codex```-Open the example here: [`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html).+Replace `codex` with `claude-code` or `opencode` when needed.-+### 2. Ask for one clear view-Data Flow diagrams explain how data assets move and change:+Start with an overview instead of asking one diagram to explain the entire repository:```text-Use archify to draw a data flow:-Web and Mobile emit analytics events, Edge API collects them, Consent Gate filters PII, Kafka carries accepted events,-Warehouse stores analytics tables, Feature Store derives daily features, Dashboards and an ML Model consume downstream data.+Analyze this repository, then use archify to create a high-level runtime architecture diagram.+Show 8–12 core components, one primary request or data path, external dependencies, and trust boundaries.+Put supporting detail in cards instead of adding more edges.```-Open the example here: [`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html).----Lifecycle diagrams explain how an object changes state:+For a focused flow:```text-Use archify to draw a lifecycle diagram:-Agent Run starts at Queued, moves through Planning, Executing, and Reviewing. It can pause at Needs Approval,-wait at Blocked, retry after Failed, end at Cancelled or Expired, or finish at Completed.+Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->+Redis session lookup -> PostgreSQL fallback. Make the cache-miss path secondary.```-Open the example here: [`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html).+### 3. Refine in chat---## What's new--Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed the raster upsampling bug and made exports genuinely sharp at up to 4× source resolution. **2.4** upgraded SVG export to a dual-theme self-contained file. **2.5** added renderer-backed workflow / sequence / data-flow / lifecycle modes, Mermaid input guidance, CJK-aware text measurement, golden tests, and CI. **2.6** brought the architecture renderer to schema + layout validation parity. **2.7** hardens workflow diagrams with phase headers, groups, exception lanes, happy-path linting, same-lane orthogonal routing, and a post-render HTML/SVG checker. **2.8** adds opt-in trace animation and rejects workflow routes that cross unrelated nodes. **2.9** adds a unified CLI (`bin/archify.mjs`) and real-repo architecture examples. **2.10** adds actionable validator hints, optional architecture grid placement (`row`/`col`), and `archify inspect` for computed layout JSON.--| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 | 2.8 | 2.9 | 2.10 |-|---|---|---|---|---|---|---|---|---|---|---|---|---|-| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Same | Same | Same |-| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same | Same | Same | Same | Same | Same |-| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** | Same | Same | Same | Same | Same |-| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) | Same | Same | Same | Same | Same |-| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** | Same | Same | Same | Same | Same |-| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same | Same | Same | Same | Same | Same |-| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) | Same | Same | Same | Same | Same |-| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same | Same | Same | Same | Same | Same |-| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** | Same | Same | Same | Same | Same |-| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same | Same | Same | Same | Same | Same |-| Typed renderers + schema validation | — | — | — | — | — | — | Workflow / sequence / data-flow / lifecycle | **+ architecture** | Same | Same | Same | Same |-| Workflow structure aids | — | — | — | — | — | — | Lanes + routed edges | Same | **Phases, groups, exception lanes, mainPath lint** | **Route-crossing guard** | Same | Same |-| Post-render artifact checker | — | — | — | — | — | — | — | — | **Yes** | Same | Same | Same |-| Trace animation | — | — | — | — | — | — | — | — | — | **Opt-in** | Same | Same |-| Unified CLI | — | — | — | — | — | — | — | — | — | — | **Yes** | Same |-| Real-repo architecture examples | — | — | — | — | — | — | — | — | — | — | **Yes** | Same |-| Architecture grid + layout inspect | — | — | — | — | — | — | — | — | — | — | — | **Yes** |-| Validator actionable hints | — | — | — | — | — | — | — | — | — | — | — | **Yes** |+Ask for focused changes such as `add Redis`, `move auth to the left`, or `highlight the rollback path` while the source JSON remains available in the session.-## Quick start+Archify returns a self-contained HTML file that opens in any modern browser and exports to PNG, JPEG, WebP, or SVG.-### 1. Install in one command--Install Archify globally, then select your agent when prompted:+## Diagram types-```bash-npx skills add tt-a1i/archify -g-```+Choose the view that matches the question you need to answer:-Want to try it without a permanent install? This starts Codex with a temporary copy of the skill:+| Type | Best for | Include in your prompt |+|---|---|---|+| **Architecture** | Components, services, storage, boundaries | Scope, core components, primary path |+| **Workflow** | CI/CD, approvals, tool calls, runbooks | Participants, order, branches, exceptions |+| **Sequence** | API calls, cache fallback, auth, async traces | Callers, callees, returns, timing |+| **Data Flow** | Pipelines, lineage, PII, downstream consumers | Sources, transforms, stores, boundaries |+| **Lifecycle** | State machines, retries, waits, terminal states | States, events, retry and cancellation paths |-```bash-npx skills use tt-a1i/archify@archify --agent codex-```+Architecture examples:-Replace `codex` with `claude-code` or `opencode` to start either of those agents instead. These commands use the open-source [`skills` CLI](https://github.com/vercel-labs/skills).+- [`examples/web-app.html`](examples/web-app.html) — compact SaaS architecture+- [`examples/archify-repo.html`](examples/archify-repo.html) — Archify's skill → JSON IR → renderer pipeline+- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — explicit `row` / `col` grid placement+- [`examples/maka-architecture.html`](examples/maka-architecture.html) — a third-party desktop agent workbench-### 2. Copy one prompt+Workflow uses swimlanes, a clear happy path, and restrained secondary branches.-**Map a real repository:**+-```text-Analyze this repository, then use archify to create an architecture diagram of its runtime components, data flow, external dependencies, and trust boundaries.-```+Sequence focuses on one interaction over time.-**Explain a request path:**+-```text-Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation -> Redis session lookup -> PostgreSQL fallback. Show the cache-miss path clearly.-```+Data Flow makes movement, transformation, and sensitivity boundaries explicit.-**Visualize delivery:**+-```text-Use archify to create a CI/CD workflow diagram: pull request -> tests -> approval gate -> build image -> staging deploy -> smoke test -> production deploy, with rollback on failure.-```+Lifecycle separates normal progress, wait states, retries, and terminal outcomes.-The distributed skill includes standalone Schema validators, so it is ready to render immediately — no `npm install` or runtime dependencies required.+-### 3. Iterate in chat+## Why Archify-Ask for focused changes such as `add Redis`, `move auth to the left`, or `highlight the rollback path`. Archify returns a self-contained HTML file you can open in any browser and export as PNG, JPEG, WebP, or SVG.+- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story being told.+- **Typed JSON IR** — architecture, workflow, sequence, data-flow, and lifecycle diagrams use renderer-backed schemas.+- **Validation before delivery** — schema, layout, HTML, and SVG checks catch malformed or unreadable output early.+- **Portable output** — one HTML file, no server or framework required, with local font fallbacks when external fonts are unavailable.+- **Semantic technology labels** — names such as `postgres`, `redis`, `aws.lambda`, and `github-actions` guide visual categorization without a heavyweight icon runtime.-### Other installation methods+Archify is not a general-purpose drawing editor or a Mermaid theme. Its job is to turn technical intent into a polished communication artifact.-Archify is packaged as an agent skill directory (`archify/SKILL.md`), so the same [`archify.zip`](archify.zip) works with Claude, Codex CLI, and opencode.+## Installation options-**Claude.ai:**-1. Download [`archify.zip`](archify.zip)-2. Go to **Settings** -> **Capabilities** -> **Skills**-3. Click **+ Add** and upload the zip file-4. Toggle the skill on+The primary installation command is:-**Claude Code CLI:**```bash-# Global (all projects)-unzip archify.zip -d ~/.claude/skills/--# Or project-local-unzip archify.zip -d ./.claude/skills/+npx skills add tt-a1i/archify -g```-**Codex CLI:**-```bash-# Global (all projects)-unzip archify.zip -d ~/.agents/skills/+The same [`archify.zip`](archify.zip) can also be installed manually:-# Or project-local-unzip archify.zip -d ./.agents/skills/-```+| Surface | Install location or method | Capability |+|---|---|---|+| **Claude Code** | `~/.claude/skills/` or `.claude/skills/` | Full renderer + validation workflow |+| **Codex CLI** | `~/.agents/skills/` or `.agents/skills/` | Full renderer + validation workflow |+| **opencode** | `~/.config/opencode/skills/`, `.opencode/skills/`, or `.agents/skills/` | Full renderer + validation workflow |+| **Claude.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |+| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture mode only |-**opencode:**-```bash-# Global (opencode-native)-unzip archify.zip -d ~/.config/opencode/skills/+Manual installation means unzipping the archive into the matching directory. No `npm install` is required for the packaged skill.-# Or project-local-unzip archify.zip -d ./.opencode/skills/+## How it works-# Also works: the shared agent directory used above for Codex-unzip archify.zip -d ~/.agents/skills/-```--Renderer-backed diagrams follow a small quality loop before delivery:+Renderer-backed diagrams follow a small, inspectable loop:| Step | What happens ||---|---|-| **Generate JSON IR** | The agent writes a typed architecture / workflow / sequence / dataflow / lifecycle description instead of hand-editing the final SVG. |-| **Validate** | Bundled standalone validators check the JSON Schema with no runtime dependency installation. |-| **Render** | The typed renderer produces the self-contained HTML/SVG output. |-| **Check artifact** | The post-render checker catches malformed SVG, non-finite coordinates, accidental diagonal arrows, and legend-crossing routes. |-| **Iterate** | Fixes are made against the JSON IR or semantic classes, so targeted edits do not require regenerating the whole diagram from scratch. |--You can run the final artifact check directly:--```bash-node scripts/check-render-output.mjs output.html-```+| **Generate JSON IR** | The agent creates a typed description instead of hand-editing final SVG markup. |+| **Validate** | Bundled standalone validators check the schema without installing runtime dependencies. |+| **Render** | The selected renderer produces the HTML/SVG artifact. |+| **Check** | Layout and artifact checks catch invalid coordinates, malformed SVG, and unsafe routes. |+| **Iterate** | Targeted changes are applied to the JSON IR while unrelated structure stays stable. |-The bundled CLI wraps the same renderer and checker commands:+The packaged CLI exposes the same workflow. From a repository checkout:```bash+cd archifynode bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demo-node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json workflow.html+node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.htmlnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json-node bin/archify.mjs check workflow.html+node bin/archify.mjs check /tmp/workflow.htmlnode bin/archify.mjs examples```-Renderer-backed diagrams can also opt into lightweight motion for demos:+Optional trace animation can be enabled for demos:```json{ "meta": { "title": "Release Flow", "animation": "trace" } }```-Trace animation runs inside the generated HTML/SVG: arrows flow in order, nodes pulse lightly, and `prefers-reduced-motion` disables movement for users who request it. Omit `animation` for the default static diagram.--**Claude.ai Projects (alternative):**-Upload [`archify.zip`](archify.zip) to your Project Knowledge.--What each install surface can do:--| Install surface | Capability |-|---|---|-| **Claude Code** | Full — runs the typed renderers + schema validation |-| **Codex CLI** | Full — install to `~/.agents/skills/` or `.agents/skills/` |-| **opencode** | Full — install to `.opencode/skills/`, `.agents/skills/`, or another supported skills directory |-| **Claude.ai (zip upload)** | Usually full — depends on whether the sandbox allows Node.js execution |-| **Project Knowledge** | Architecture mode only — no code execution, purely prompt-driven |+The animation respects `prefers-reduced-motion`. Omit `animation` for a static diagram.## Using the output-Open the generated HTML in any browser. Top-right you'll see two buttons:--- **Theme button** (Dark / Light) — one click flip, persisted across sessions. Shortcut: <kbd>T</kbd>.-- **Export menu** — opens a dropdown with five actions (Copy PNG + download PNG / JPEG / WebP / SVG). Shortcut: <kbd>E</kbd>.+Open the generated HTML in a modern browser. The controls in the top-right provide:-### Export menu+- **Theme** — switch between dark and light. Shortcut: <kbd>T</kbd>.+- **Export** — copy PNG or download PNG, JPEG, WebP, or SVG. Shortcut: <kbd>E</kbd>.-| Action | What it does |+| Format | Use it for ||---|---|-| **Copy PNG** | Puts a PNG of the current diagram straight on your clipboard. Paste into Slack, Notion, GitHub, Figma. |-| **Download PNG / JPEG / WebP** | Saves a raster image. JPEG/WebP are painted over the current theme's background (no alpha); PNG keeps transparency. |-| **Download SVG** | Vector export with all styles inlined, **dual-theme self-contained**. The file ships with both dark and light CSS variable sets plus a `@media (prefers-color-scheme)` rule — drop the same `.svg` into a GitHub README or blog and it follows the reader's preference automatically. Still editable in Figma / Illustrator. Scales losslessly. |+| **Copy PNG** | Slack, Notion, GitHub comments, and quick reviews |+| **PNG / JPEG / WebP** | Slides, documents, websites, and print |+| **SVG** | READMEs, blogs, Figma, Illustrator, and lossless scaling |-Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **up to 4× the diagram's intrinsic resolution** (oversized diagrams step down to 3×/2× to stay within browser canvas limits) — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum safe sharpness is always chosen automatically.+Raster exports are rendered natively at the highest safe resolution, up to 4×. Oversized diagrams step down automatically to stay within browser canvas limits.-### Keyboard+Exported SVGs include dark and light variables plus `prefers-color-scheme`, so one SVG can follow the reader's system theme.-- <kbd>T</kbd> anywhere — toggle theme-- <kbd>E</kbd> anywhere — open the Export menu-- <kbd>↑</kbd> <kbd>↓</kbd> inside the menu — navigate actions-- <kbd>Home</kbd> / <kbd>End</kbd> — jump to first / last action-- <kbd>Enter</kbd> / <kbd>Space</kbd> — activate-- <kbd>Esc</kbd> — close menu+Useful URL parameters:-### URL parameters+- `?theme=light` or `?theme=dark` — force the starting theme.+- `?openExport=1` — open the Export menu on load.-- `?theme=light` or `?theme=dark` — force a starting theme (deterministic screenshots, share links, embeds)-- `?openExport=1` — auto-open the Export menu on load (demo / docs screenshots)+WebP and clipboard support depend on browser capabilities. The HTML uses local font fallbacks when an external font cannot be loaded.-### Notes+## Prompt patterns-- **WebP support** depends on your browser's canvas encoder. If unavailable (older Safari), the menu item is dimmed and disabled. PNG and JPEG are universal.-- **Clipboard support** for images requires `ClipboardItem` + `navigator.clipboard.write` (Chromium, Firefox 127+, Safari 16+). If unavailable, Copy PNG is dimmed.-- **Fonts in exports**: raster images use the system monospace fallback (`ui-monospace` / Menlo / Consolas) because the sandboxed image-rendering context can't fetch Google Fonts. Install JetBrains Mono locally for pixel-perfect rendering.+**Repository overview**-## Example prompts--**Web app:**-```-Create an architecture diagram for a web application with:-- React frontend-- Node.js/Express API-- PostgreSQL database-- Redis cache-- JWT authentication+```text+Map this repository's runtime architecture with no more than 12 core components.+Show the main request path, external systems, and trust boundaries. Move implementation detail into cards.```-**AWS serverless:**-```-Create an architecture diagram showing:-- CloudFront CDN-- API Gateway-- Lambda functions (Node.js)-- DynamoDB-- S3 for static assets-- Cognito for auth-```+**CI/CD workflow**-**Microservices:**-```-Create an architecture diagram for a microservices system with:-- React web app and mobile clients-- Kong API Gateway-- User Service (Go), Order Service (Java), Product Service (Python)-- PostgreSQL, MongoDB, and Elasticsearch databases-- Kafka for event streaming-- Kubernetes orchestration+```text+Draw a CI/CD workflow: pull request -> tests -> approval -> build image -> staging ->+smoke test -> production. Show rollback as a secondary failure path.```-**Data flow / product analytics:**-```-Use archify to draw a data flow:-- Web App and Mobile SDK produce clickstream events-- Edge API collects events-- Consent Gate filters identity and PII-- Kafka/Event Stream carries accepted events-- Warehouse stores normalized facts-- Feature Store derives daily feature vectors-- Dashboards and ML Model consume downstream data-```+**Data lineage**-**State machine / lifecycle:**-```-Use archify to draw a lifecycle diagram:-- A task starts at Queued-- Planning builds the plan-- Executing calls tools-- Reviewing checks quality-- Needs Approval and Blocked are wait states-- Failed can retry, while Cancelled / Expired / Completed are terminal states+```text+Draw a data-flow diagram from Web and Mobile events through Consent Gate, Kafka,+Warehouse, and Feature Store to Dashboards and ML consumers. Mark the PII boundary.```-## Color palette--| Component Type | Color | Use for |-| -------------- | ------- | --------------------------------- |-| Frontend | Cyan | Client apps, UI, edge devices |-| Backend | Emerald | Servers, APIs, services |-| Database | Violet | Databases, storage, AI/ML |-| Cloud / AWS | Amber | Cloud services, infrastructure |-| Security | Rose | Auth, security groups, encryption |-| Message Bus | Orange | Kafka, RabbitMQ, SNS, event buses |-| External | Slate | Generic, external systems |--Each color has coordinated dark-mode and light-mode variants that switch together via the theme toggle.+## Reference-### Semantic tech labels+Semantic labels guide color and grouping:-Archify is not trying to ship a complete AWS / Azure / GCP icon runtime. Instead, it treats technology names and optional labels as semantic hints that guide color, grouping, and copy:--| Label examples | Visual category |+| Examples | Category ||---|---|-| `react`, `nextjs`, `ios`, `android`, `browser` | Frontend |+| `react`, `nextjs`, `ios`, `browser` | Frontend || `node`, `go-service`, `python-worker`, `api-gateway` | Backend |-| `postgres`, `mysql`, `redis`, `s3`, `bigquery`, `snowflake` | Database / storage |-| `aws.lambda`, `aws.cloudfront`, `gcp.pubsub`, `azure.functions`, `kubernetes` | Cloud / infrastructure |-| `auth0`, `cognito`, `oauth`, `vault`, `security-group` | Security |-| `kafka`, `rabbitmq`, `sns`, `sqs`, `nats` | Message bus |-| `stripe`, `github-actions`, `openai`, `anthropic`, `slack` | External |--Use these labels in prompts or JSON IR when the exact technology matters. The generated diagram stays self-contained HTML/SVG; the labels improve semantic styling and layout without forcing a heavyweight icon dependency.+| `postgres`, `redis`, `s3`, `bigquery`, `snowflake` | Data and storage |+| `aws.lambda`, `gcp.pubsub`, `azure.functions`, `kubernetes` | Cloud and infrastructure |+| `auth0`, `oauth`, `vault`, `security-group` | Security |+| `kafka`, `rabbitmq`, `sqs`, `nats` | Messaging |+| `stripe`, `github-actions`, `openai`, `slack` | External systems |-## Technical details+See the [schema reference](archify/schemas/README.md) for renderer inputs and [CHANGELOG.md](CHANGELOG.md) for release history.-- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.-- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.-- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~19 KB of embedded JS. No build step, no JS framework, no server. The generated HTML and the distributed renderer have zero runtime dependencies.-- **Output checks:** `bin/archify.mjs validate`, renderer layout checks, and `scripts/check-render-output.mjs` validate generated diagrams before delivery: schema validity, finite SVG values, no accidental two-point diagonal arrows, and no arrow segments crossing the legend.-- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.+## Current status and roadmap-## Attribution--Archify is a fork / rewrite of [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT, v1.0) by [Cocoon AI](mailto:[email protected]). The original's clean visual design — color palette, grid background, summary-card layout, JetBrains Mono typography — is preserved. All credit for the original aesthetic belongs to them.--Archify 2.x contributes:-- Refactor of the template to a CSS-variable theme system (dark + light)-- Theme toggle + `localStorage` persistence + `prefers-color-scheme` default-- Built-in PNG / JPEG / WebP / SVG export menu + copy to clipboard-- 4× native rasterization (fixes upsampling blur)-- Dual-theme self-contained SVG export (single file follows the host's `prefers-color-scheme`)-- Keyboard navigation + accessibility semantics-- Print stylesheet + local-font fallback-- Renderer-backed architecture, workflow, sequence, data-flow, and lifecycle diagrams with schema validation-- Post-render artifact checks for final HTML/SVG quality-- Unified CLI (`bin/archify.mjs`) for render / validate / check / examples-- Real-repo architecture examples (`archify-repo`, `maka-architecture`)-- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams+Archify 2.10 already uses typed JSON IR across all five renderer-backed modes. Current work focuses on stabilizing local edits, improving layout diagnostics, and keeping generated artifacts easy to inspect and share.-Both projects are MIT-licensed.+See [ROADMAP.md](ROADMAP.md) for planned work and design boundaries. Automatic Mermaid parsing, generic auto-layout, a hosted sharing service, and a WYSIWYG editor are not current goals.-## Roadmap--See [ROADMAP.md](ROADMAP.md).+## Attribution-Next up is **v3.0 — JSON IR stabilization**: a minimal `diagram.json` intermediate format so Claude can make local coordinate edits without drifting unrelated components, with `git diff`-friendly output and theme/palette swaps that don't require re-rendering.+Archify is a fork and rewrite of [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 by Cocoon AI.-> **About Mermaid import:** the automatic Mermaid parser route was cut after an experiment showed that auto-layout + archify CSS doesn't look meaningfully better than native Mermaid ([experiments/v3-mermaid-validation/RESULT.md](experiments/v3-mermaid-validation/RESULT.md)). Archify's aesthetic core is Claude's layout judgment, not the CSS. You can still paste Mermaid code and have Claude lay out an archify-style diagram from scratch — it goes through the `SKILL.md` prompts, not a parser.->-> The former v2.4 / v2.5 plans (`?exportScale=N`, color-blind palettes, share links) were also dropped. See the [ROADMAP "Not planned" section](ROADMAP.md#not-planned) for the rationale.+The original visual language remains credited to that project. Archify 2.x adds themes, export tooling, typed renderers, validation, accessibility, and the unified CLI. Both projects use the MIT license.## License@@ -449,4 +270,4 @@ Next up is **v3.0 — JSON IR stabilization**: a minimal `diagram.json` intermed## Contributing-Issues, PRs, and shared diagrams welcome.+Issues, pull requests, and shared diagrams are welcome. When reporting generated-output problems, include the prompt, diagram type, and Archify version when possible.diff --git a/README_EN.md b/README_EN.mdindex 19575bc1..6758f6da 100644--- a/README_EN.md+++ b/README_EN.md@@ -1,3 +1,7 @@+<p align="center">+ <a href="https://trendshift.io/repositories/31352?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-31352" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/31352" alt="Archify on Trendshift" width="250" height="55"/></a>+</p>+# Archify@@ -45,399 +49,220 @@ The Export menu — Copy PNG to clipboard plus 4 download formats (all raster ex-Live example: [`examples/web-app.html`](examples/web-app.html) — open in a browser, press <kbd>T</kbd> to toggle theme, <kbd>E</kbd> to open Export. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.--## Diagram types--Archify now has five primary outputs:--| Type | Good for | How to ask |-|---|---|---|-| **Architecture** | System components, cloud resources, databases, caches, services, boundaries, security groups | Describe the system structure |-| **Workflow** | Request lifecycles, approval flows, tool calls, CI/CD, runbooks, incident response | Describe participants, step order, and key branches |-| **Sequence** | API call chains, request lifecycles, cache fallback, auth checks, async trace, service interactions | Describe who calls whom, in what order, and what returns |-| **Data Flow** | Data pipelines, ETL/ELT, analytics events, PII isolation, warehouse sync, lineage, downstream consumers | Describe sources, processing stages, storage, sensitivity boundaries, and consumers |-| **Lifecycle** | State machines, order/task/deployment/agent-run lifecycles, wait states, retries, cancellation, timeout, terminal states | Describe states, transition events, retry paths, and terminal outcomes |--Architecture diagrams explain system structure — components, boundaries, and how they connect:--```text-Use archify to draw an architecture diagram:-React frontend calls a Node.js API backed by PostgreSQL and Redis, deployed on AWS behind CloudFront.-```--Sample SaaS diagram: [`examples/web-app.html`](examples/web-app.html).+Example file: [`examples/web-app.html`](examples/web-app.html). Download or clone the repository, open the file locally, then press <kbd>T</kbd> to toggle themes or <kbd>E</kbd> to open Export.-Real-repo examples (renderer-backed JSON IR):--- [`examples/archify-repo.html`](examples/archify-repo.html) — this project's skill → JSON IR → renderers pipeline-- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — same pipeline with `layout.mode: "grid"` (`row`/`col` placement)-- [`examples/maka-architecture.html`](examples/maka-architecture.html) — third-party desktop agent workbench (Maka)+## Quick start-Workflow is not trying to replace every general-purpose flowchart. It is a technical communication diagram: swimlanes, semantic colors, a clear happy path, and secondary async / approval / trace paths.+### 1. Install-```text-Use archify to draw a workflow:-User submits a request -> Agent plans -> Approval Gate if needed -> Tool Call -> Trace Log -> Final Reply+```bash+npx skills add tt-a1i/archify -g```-Open the example here: [`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html).+This installs Archify for supported agents through the open-source [`skills` CLI](https://github.com/vercel-labs/skills).---Sequence diagrams explain a narrower interaction over time:+To try it without a permanent install:-```text-Use archify to draw a sequence diagram:-User opens a page, the frontend calls the API, the API verifies JWT, reads Redis, falls back to Postgres on cache miss, returns JSON, and emits trace.+```bash+npx skills use tt-a1i/archify@archify --agent codex```-Open the example here: [`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html).+Replace `codex` with `claude-code` or `opencode` when needed.-+### 2. Ask for one clear view-Data Flow diagrams explain how data assets move and change:+Start with an overview instead of asking one diagram to explain the entire repository:```text-Use archify to draw a data flow:-Web and Mobile emit analytics events, Edge API collects them, Consent Gate filters PII, Kafka carries accepted events,-Warehouse stores analytics tables, Feature Store derives daily features, Dashboards and an ML Model consume downstream data.+Analyze this repository, then use archify to create a high-level runtime architecture diagram.+Show 8–12 core components, one primary request or data path, external dependencies, and trust boundaries.+Put supporting detail in cards instead of adding more edges.```-Open the example here: [`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html).----Lifecycle diagrams explain how an object changes state:+For a focused flow:```text-Use archify to draw a lifecycle diagram:-Agent Run starts at Queued, moves through Planning, Executing, and Reviewing. It can pause at Needs Approval,-wait at Blocked, retry after Failed, end at Cancelled or Expired, or finish at Completed.+Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->+Redis session lookup -> PostgreSQL fallback. Make the cache-miss path secondary.```-Open the example here: [`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html).+### 3. Refine in chat-+Ask for focused changes such as `add Redis`, `move auth to the left`, or `highlight the rollback path` while the source JSON remains available in the session.-## What's new--Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed the raster upsampling bug and made exports genuinely sharp at up to 4× source resolution. **2.4** upgraded SVG export to a dual-theme self-contained file. **2.5** added renderer-backed workflow / sequence / data-flow / lifecycle modes, Mermaid input guidance, CJK-aware text measurement, golden tests, and CI. **2.6** brought the architecture renderer to schema + layout validation parity. **2.7** hardens workflow diagrams with phase headers, groups, exception lanes, happy-path linting, same-lane orthogonal routing, and a post-render HTML/SVG checker. **2.8** adds opt-in trace animation and rejects workflow routes that cross unrelated nodes. **2.9** adds a unified CLI (`bin/archify.mjs`) and real-repo architecture examples. **2.10** adds actionable validator hints, optional architecture grid placement (`row`/`col`), and `archify inspect` for computed layout JSON.--| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 | 2.8 | 2.9 | 2.10 |-|---|---|---|---|---|---|---|---|---|---|---|---|---|-| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Same | Same | Same |-| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same | Same | Same | Same | Same | Same |-| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** | Same | Same | Same | Same | Same |-| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) | Same | Same | Same | Same | Same |-| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** | Same | Same | Same | Same | Same |-| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same | Same | Same | Same | Same | Same |-| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) | Same | Same | Same | Same | Same |-| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same | Same | Same | Same | Same | Same |-| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** | Same | Same | Same | Same | Same |-| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same | Same | Same | Same | Same | Same |-| Typed renderers + schema validation | — | — | — | — | — | — | Workflow / sequence / data-flow / lifecycle | **+ architecture** | Same | Same | Same | Same |-| Workflow structure aids | — | — | — | — | — | — | Lanes + routed edges | Same | **Phases, groups, exception lanes, mainPath lint** | **Route-crossing guard** | Same | Same |-| Post-render artifact checker | — | — | — | — | — | — | — | — | **Yes** | Same | Same | Same |-| Trace animation | — | — | — | — | — | — | — | — | — | **Opt-in** | Same | Same |-| Unified CLI | — | — | — | — | — | — | — | — | — | — | **Yes** | Same |-| Real-repo architecture examples | — | — | — | — | — | — | — | — | — | — | **Yes** | Same |-| Architecture grid + layout inspect | — | — | — | — | — | — | — | — | — | — | — | **Yes** |-| Validator actionable hints | — | — | — | — | — | — | — | — | — | — | — | **Yes** |+Archify returns a self-contained HTML file that opens in any modern browser and exports to PNG, JPEG, WebP, or SVG.-## Quick start--### 1. Install in one command+## Diagram types-Install Archify globally, then select your agent when prompted:+Choose the view that matches the question you need to answer:-```bash-npx skills add tt-a1i/archify -g-```--Want to try it without a permanent install? This starts Codex with a temporary copy of the skill:+| Type | Best for | Include in your prompt |+|---|---|---|+| **Architecture** | Components, services, storage, boundaries | Scope, core components, primary path |+| **Workflow** | CI/CD, approvals, tool calls, runbooks | Participants, order, branches, exceptions |+| **Sequence** | API calls, cache fallback, auth, async traces | Callers, callees, returns, timing |+| **Data Flow** | Pipelines, lineage, PII, downstream consumers | Sources, transforms, stores, boundaries |+| **Lifecycle** | State machines, retries, waits, terminal states | States, events, retry and cancellation paths |-```bash-npx skills use tt-a1i/archify@archify --agent codex-```+Architecture examples:-Replace `codex` with `claude-code` or `opencode` to start either of those agents instead. These commands use the open-source [`skills` CLI](https://github.com/vercel-labs/skills).+- [`examples/web-app.html`](examples/web-app.html) — compact SaaS architecture+- [`examples/archify-repo.html`](examples/archify-repo.html) — Archify's skill → JSON IR → renderer pipeline+- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — explicit `row` / `col` grid placement+- [`examples/maka-architecture.html`](examples/maka-architecture.html) — a third-party desktop agent workbench-### 2. Copy one prompt+Workflow uses swimlanes, a clear happy path, and restrained secondary branches.-**Map a real repository:**+-```text-Analyze this repository, then use archify to create an architecture diagram of its runtime components, data flow, external dependencies, and trust boundaries.-```+Sequence focuses on one interaction over time.-**Explain a request path:**+-```text-Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation -> Redis session lookup -> PostgreSQL fallback. Show the cache-miss path clearly.-```+Data Flow makes movement, transformation, and sensitivity boundaries explicit.-**Visualize delivery:**+-```text-Use archify to create a CI/CD workflow diagram: pull request -> tests -> approval gate -> build image -> staging deploy -> smoke test -> production deploy, with rollback on failure.-```+Lifecycle separates normal progress, wait states, retries, and terminal outcomes.-The distributed skill includes standalone Schema validators, so it is ready to render immediately — no `npm install` or runtime dependencies required.+-### 3. Iterate in chat+## Why Archify-Ask for focused changes such as `add Redis`, `move auth to the left`, or `highlight the rollback path`. Archify returns a self-contained HTML file you can open in any browser and export as PNG, JPEG, WebP, or SVG.+- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story being told.+- **Typed JSON IR** — architecture, workflow, sequence, data-flow, and lifecycle diagrams use renderer-backed schemas.+- **Validation before delivery** — schema, layout, HTML, and SVG checks catch malformed or unreadable output early.+- **Portable output** — one HTML file, no server or framework required, with local font fallbacks when external fonts are unavailable.+- **Semantic technology labels** — names such as `postgres`, `redis`, `aws.lambda`, and `github-actions` guide visual categorization without a heavyweight icon runtime.-### Other installation methods+Archify is not a general-purpose drawing editor or a Mermaid theme. Its job is to turn technical intent into a polished communication artifact.-Archify is packaged as an agent skill directory (`archify/SKILL.md`), so the same [`archify.zip`](archify.zip) works with Claude, Codex CLI, and opencode.+## Installation options-**Claude.ai:**-1. Download [`archify.zip`](archify.zip)-2. Go to **Settings** -> **Capabilities** -> **Skills**-3. Click **+ Add** and upload the zip file-4. Toggle the skill on+The primary installation command is:-**Claude Code CLI:**```bash-# Global (all projects)-unzip archify.zip -d ~/.claude/skills/--# Or project-local-unzip archify.zip -d ./.claude/skills/+npx skills add tt-a1i/archify -g```-**Codex CLI:**-```bash-# Global (all projects)-unzip archify.zip -d ~/.agents/skills/+The same [`archify.zip`](archify.zip) can also be installed manually:-# Or project-local-unzip archify.zip -d ./.agents/skills/-```--**opencode:**-```bash-# Global (opencode-native)-unzip archify.zip -d ~/.config/opencode/skills/+| Surface | Install location or method | Capability |+|---|---|---|+| **Claude Code** | `~/.claude/skills/` or `.claude/skills/` | Full renderer + validation workflow |+| **Codex CLI** | `~/.agents/skills/` or `.agents/skills/` | Full renderer + validation workflow |+| **opencode** | `~/.config/opencode/skills/`, `.opencode/skills/`, or `.agents/skills/` | Full renderer + validation workflow |+| **Claude.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |+| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture mode only |-# Or project-local-unzip archify.zip -d ./.opencode/skills/+Manual installation means unzipping the archive into the matching directory. No `npm install` is required for the packaged skill.-# Also works: the shared agent directory used above for Codex-unzip archify.zip -d ~/.agents/skills/-```+## How it works-Renderer-backed diagrams follow a small quality loop before delivery:+Renderer-backed diagrams follow a small, inspectable loop:| Step | What happens ||---|---|-| **Generate JSON IR** | The agent writes a typed architecture / workflow / sequence / dataflow / lifecycle description instead of hand-editing the final SVG. |-| **Validate** | Bundled standalone validators check the JSON Schema with no runtime dependency installation. |-| **Render** | The typed renderer produces the self-contained HTML/SVG output. |-| **Check artifact** | The post-render checker catches malformed SVG, non-finite coordinates, accidental diagonal arrows, and legend-crossing routes. |-| **Iterate** | Fixes are made against the JSON IR or semantic classes, so targeted edits do not require regenerating the whole diagram from scratch. |--You can run the final artifact check directly:--```bash-node scripts/check-render-output.mjs output.html-```+| **Generate JSON IR** | The agent creates a typed description instead of hand-editing final SVG markup. |+| **Validate** | Bundled standalone validators check the schema without installing runtime dependencies. |+| **Render** | The selected renderer produces the HTML/SVG artifact. |+| **Check** | Layout and artifact checks catch invalid coordinates, malformed SVG, and unsafe routes. |+| **Iterate** | Targeted changes are applied to the JSON IR while unrelated structure stays stable. |-The bundled CLI wraps the same renderer and checker commands:+The packaged CLI exposes the same workflow. From a repository checkout:```bash+cd archifynode bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demo-node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json workflow.html+node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.htmlnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json-node bin/archify.mjs check workflow.html+node bin/archify.mjs check /tmp/workflow.htmlnode bin/archify.mjs examples```-Renderer-backed diagrams can also opt into lightweight motion for demos:+Optional trace animation can be enabled for demos:```json{ "meta": { "title": "Release Flow", "animation": "trace" } }```-Trace animation runs inside the generated HTML/SVG: arrows flow in order, nodes pulse lightly, and `prefers-reduced-motion` disables movement for users who request it. Omit `animation` for the default static diagram.--**Claude.ai Projects (alternative):**-Upload [`archify.zip`](archify.zip) to your Project Knowledge.--What each install surface can do:--| Install surface | Capability |-|---|---|-| **Claude Code** | Full — runs the typed renderers + schema validation |-| **Codex CLI** | Full — install to `~/.agents/skills/` or `.agents/skills/` |-| **opencode** | Full — install to `.opencode/skills/`, `.agents/skills/`, or another supported skills directory |-| **Claude.ai (zip upload)** | Usually full — depends on whether the sandbox allows Node.js execution |-| **Project Knowledge** | Architecture mode only — no code execution, purely prompt-driven |+The animation respects `prefers-reduced-motion`. Omit `animation` for a static diagram.## Using the output-Open the generated HTML in any browser. Top-right you'll see two buttons:+Open the generated HTML in a modern browser. The controls in the top-right provide:-- **Theme button** (Dark / Light) — one click flip, persisted across sessions. Shortcut: <kbd>T</kbd>.-- **Export menu** — opens a dropdown with five actions (Copy PNG + download PNG / JPEG / WebP / SVG). Shortcut: <kbd>E</kbd>.+- **Theme** — switch between dark and light. Shortcut: <kbd>T</kbd>.+- **Export** — copy PNG or download PNG, JPEG, WebP, or SVG. Shortcut: <kbd>E</kbd>.-### Export menu--| Action | What it does |+| Format | Use it for ||---|---|-| **Copy PNG** | Puts a PNG of the current diagram straight on your clipboard. Paste into Slack, Notion, GitHub, Figma. |-| **Download PNG / JPEG / WebP** | Saves a raster image. JPEG/WebP are painted over the current theme's background (no alpha); PNG keeps transparency. |-| **Download SVG** | Vector export with all styles inlined, **dual-theme self-contained**. The file ships with both dark and light CSS variable sets plus a `@media (prefers-color-scheme)` rule — drop the same `.svg` into a GitHub README or blog and it follows the reader's preference automatically. Still editable in Figma / Illustrator. Scales losslessly. |--Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **up to 4× the diagram's intrinsic resolution** (oversized diagrams step down to 3×/2× to stay within browser canvas limits) — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum safe sharpness is always chosen automatically.+| **Copy PNG** | Slack, Notion, GitHub comments, and quick reviews |+| **PNG / JPEG / WebP** | Slides, documents, websites, and print |+| **SVG** | READMEs, blogs, Figma, Illustrator, and lossless scaling |-### Keyboard+Raster exports are rendered natively at the highest safe resolution, up to 4×. Oversized diagrams step down automatically to stay within browser canvas limits.-- <kbd>T</kbd> anywhere — toggle theme-- <kbd>E</kbd> anywhere — open the Export menu-- <kbd>↑</kbd> <kbd>↓</kbd> inside the menu — navigate actions-- <kbd>Home</kbd> / <kbd>End</kbd> — jump to first / last action-- <kbd>Enter</kbd> / <kbd>Space</kbd> — activate-- <kbd>Esc</kbd> — close menu+Exported SVGs include dark and light variables plus `prefers-color-scheme`, so one SVG can follow the reader's system theme.-### URL parameters+Useful URL parameters:-- `?theme=light` or `?theme=dark` — force a starting theme (deterministic screenshots, share links, embeds)-- `?openExport=1` — auto-open the Export menu on load (demo / docs screenshots)+- `?theme=light` or `?theme=dark` — force the starting theme.+- `?openExport=1` — open the Export menu on load.-### Notes+WebP and clipboard support depend on browser capabilities. The HTML uses local font fallbacks when an external font cannot be loaded.-- **WebP support** depends on your browser's canvas encoder. If unavailable (older Safari), the menu item is dimmed and disabled. PNG and JPEG are universal.-- **Clipboard support** for images requires `ClipboardItem` + `navigator.clipboard.write` (Chromium, Firefox 127+, Safari 16+). If unavailable, Copy PNG is dimmed.-- **Fonts in exports**: raster images use the system monospace fallback (`ui-monospace` / Menlo / Consolas) because the sandboxed image-rendering context can't fetch Google Fonts. Install JetBrains Mono locally for pixel-perfect rendering.+## Prompt patterns-## Example prompts+**Repository overview**-**Web app:**-```-Create an architecture diagram for a web application with:-- React frontend-- Node.js/Express API-- PostgreSQL database-- Redis cache-- JWT authentication+```text+Map this repository's runtime architecture with no more than 12 core components.+Show the main request path, external systems, and trust boundaries. Move implementation detail into cards.```-**AWS serverless:**-```-Create an architecture diagram showing:-- CloudFront CDN-- API Gateway-- Lambda functions (Node.js)-- DynamoDB-- S3 for static assets-- Cognito for auth-```+**CI/CD workflow**-**Microservices:**-```-Create an architecture diagram for a microservices system with:-- React web app and mobile clients-- Kong API Gateway-- User Service (Go), Order Service (Java), Product Service (Python)-- PostgreSQL, MongoDB, and Elasticsearch databases-- Kafka for event streaming-- Kubernetes orchestration+```text+Draw a CI/CD workflow: pull request -> tests -> approval -> build image -> staging ->+smoke test -> production. Show rollback as a secondary failure path.```-**Data flow / product analytics:**-```-Use archify to draw a data flow:-- Web App and Mobile SDK produce clickstream events-- Edge API collects events-- Consent Gate filters identity and PII-- Kafka/Event Stream carries accepted events-- Warehouse stores normalized facts-- Feature Store derives daily feature vectors-- Dashboards and ML Model consume downstream data-```+**Data lineage**-**State machine / lifecycle:**-```-Use archify to draw a lifecycle diagram:-- A task starts at Queued-- Planning builds the plan-- Executing calls tools-- Reviewing checks quality-- Needs Approval and Blocked are wait states-- Failed can retry, while Cancelled / Expired / Completed are terminal states+```text+Draw a data-flow diagram from Web and Mobile events through Consent Gate, Kafka,+Warehouse, and Feature Store to Dashboards and ML consumers. Mark the PII boundary.```-## Color palette--| Component Type | Color | Use for |-| -------------- | ------- | --------------------------------- |-| Frontend | Cyan | Client apps, UI, edge devices |-| Backend | Emerald | Servers, APIs, services |-| Database | Violet | Databases, storage, AI/ML |-| Cloud / AWS | Amber | Cloud services, infrastructure |-| Security | Rose | Auth, security groups, encryption |-| Message Bus | Orange | Kafka, RabbitMQ, SNS, event buses |-| External | Slate | Generic, external systems |--Each color has coordinated dark-mode and light-mode variants that switch together via the theme toggle.+## Reference-### Semantic tech labels+Semantic labels guide color and grouping:-Archify is not trying to ship a complete AWS / Azure / GCP icon runtime. Instead, it treats technology names and optional labels as semantic hints that guide color, grouping, and copy:--| Label examples | Visual category |+| Examples | Category ||---|---|-| `react`, `nextjs`, `ios`, `android`, `browser` | Frontend |+| `react`, `nextjs`, `ios`, `browser` | Frontend || `node`, `go-service`, `python-worker`, `api-gateway` | Backend |-| `postgres`, `mysql`, `redis`, `s3`, `bigquery`, `snowflake` | Database / storage |-| `aws.lambda`, `aws.cloudfront`, `gcp.pubsub`, `azure.functions`, `kubernetes` | Cloud / infrastructure |-| `auth0`, `cognito`, `oauth`, `vault`, `security-group` | Security |-| `kafka`, `rabbitmq`, `sns`, `sqs`, `nats` | Message bus |-| `stripe`, `github-actions`, `openai`, `anthropic`, `slack` | External |--Use these labels in prompts or JSON IR when the exact technology matters. The generated diagram stays self-contained HTML/SVG; the labels improve semantic styling and layout without forcing a heavyweight icon dependency.+| `postgres`, `redis`, `s3`, `bigquery`, `snowflake` | Data and storage |+| `aws.lambda`, `gcp.pubsub`, `azure.functions`, `kubernetes` | Cloud and infrastructure |+| `auth0`, `oauth`, `vault`, `security-group` | Security |+| `kafka`, `rabbitmq`, `sqs`, `nats` | Messaging |+| `stripe`, `github-actions`, `openai`, `slack` | External systems |-## Technical details+See the [schema reference](archify/schemas/README.md) for renderer inputs and [CHANGELOG.md](CHANGELOG.md) for release history.-- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.-- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.-- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~19 KB of embedded JS. No build step, no JS framework, no server. The generated HTML and the distributed renderer have zero runtime dependencies.-- **Output checks:** `bin/archify.mjs validate`, renderer layout checks, and `scripts/check-render-output.mjs` validate generated diagrams before delivery: schema validity, finite SVG values, no accidental two-point diagonal arrows, and no arrow segments crossing the legend.-- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.+## Current status and roadmap-## Attribution--Archify is a fork / rewrite of [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT, v1.0) by [Cocoon AI](mailto:[email protected]). The original's clean visual design — color palette, grid background, summary-card layout, JetBrains Mono typography — is preserved. All credit for the original aesthetic belongs to them.--Archify 2.x contributes:-- Refactor of the template to a CSS-variable theme system (dark + light)-- Theme toggle + `localStorage` persistence + `prefers-color-scheme` default-- Built-in PNG / JPEG / WebP / SVG export menu + copy to clipboard-- 4× native rasterization (fixes upsampling blur)-- Dual-theme self-contained SVG export (single file follows the host's `prefers-color-scheme`)-- Keyboard navigation + accessibility semantics-- Print stylesheet + local-font fallback-- Renderer-backed architecture, workflow, sequence, data-flow, and lifecycle diagrams with schema validation-- Post-render artifact checks for final HTML/SVG quality-- Unified CLI (`bin/archify.mjs`) for render / validate / check / examples-- Real-repo architecture examples (`archify-repo`, `maka-architecture`)-- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams+Archify 2.10 already uses typed JSON IR across all five renderer-backed modes. Current work focuses on stabilizing local edits, improving layout diagnostics, and keeping generated artifacts easy to inspect and share.-Both projects are MIT-licensed.+See [ROADMAP.md](ROADMAP.md) for planned work and design boundaries. Automatic Mermaid parsing, generic auto-layout, a hosted sharing service, and a WYSIWYG editor are not current goals.-## Roadmap--See [ROADMAP.md](ROADMAP.md).+## Attribution-Next up is **v3.0 — JSON IR stabilization**: a minimal `diagram.json` intermediate format so Claude can make local coordinate edits without drifting unrelated components, with `git diff`-friendly output and theme/palette swaps that don't require re-rendering.+Archify is a fork and rewrite of [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 by Cocoon AI.-> **About Mermaid import:** the automatic Mermaid parser route was cut after an experiment showed that auto-layout + archify CSS doesn't look meaningfully better than native Mermaid ([experiments/v3-mermaid-validation/RESULT.md](experiments/v3-mermaid-validation/RESULT.md)). Archify's aesthetic core is Claude's layout judgment, not the CSS. You can still paste Mermaid code and have Claude lay out an archify-style diagram from scratch — it goes through the `SKILL.md` prompts, not a parser.->-> The former v2.4 / v2.5 plans (`?exportScale=N`, color-blind palettes, share links) were also dropped. See the [ROADMAP "Not planned" section](ROADMAP.md#not-planned) for the rationale.+The original visual language remains credited to that project. Archify 2.x adds themes, export tooling, typed renderers, validation, accessibility, and the unified CLI. Both projects use the MIT license.## License@@ -445,4 +270,4 @@ Next up is **v3.0 — JSON IR stabilization**: a minimal `diagram.json` intermed## Contributing-Issues, PRs, and shared diagrams welcome.+Issues, pull requests, and shared diagrams are welcome. When reporting generated-output problems, include the prompt, diagram type, and Archify version when possible.diff --git a/README_ZH.md b/README_ZH.mdindex 4a65569f..2834b0a0 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -45,410 +45,229 @@ Export 菜单 —— 复制到剪贴板 + 四种格式下载:+想亲自体验:下载或克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html)。按 <kbd>T</kbd> 切换主题,按 <kbd>E</kbd> 打开导出菜单。-想亲自玩一下:克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html),按 <kbd>T</kbd> 切主题,<kbd>E</kbd> 打开导出菜单。给 URL 加上 `?theme=light` 或 `?openExport=1` 可以强制初始状态。+## 快速开始-## 图表类型--Archify 现在有五种主要输出:--| 类型 | 适合画什么 | 怎么用 |-|---|---|---|-| **Architecture** | 系统组件、云资源、数据库、缓存、服务边界、安全组 | 直接描述系统结构 |-| **Workflow** | 请求生命周期、审批流程、工具调用、CI/CD、运维 runbook、事故响应 | 说明参与方、步骤顺序、关键分支 |-| **Sequence** | API 调用链、请求生命周期、缓存回源、鉴权、异步 trace、服务交互 | 说明谁调用谁、先后顺序、返回路径 |-| **Data Flow** | 数据管线、ETL/ELT、埋点、PII 隔离、仓库同步、数据血缘、下游消费 | 说明数据来源、处理阶段、存储位置、敏感边界和消费方 |-| **Lifecycle** | 状态机、订单/任务/部署/Agent run 生命周期、等待态、重试、取消、超时、终态 | 说明对象有哪些状态、哪些事件触发转移、哪些状态是终态 |--Architecture 用来解释系统结构——组件、边界和连接关系。例如:--```-用 archify 画一张架构图:-React 前端调 Node.js API,PostgreSQL + Redis,部署在 AWS CloudFront 后面。-```--SaaS 样例:[`examples/web-app.html`](examples/web-app.html)--真实仓库示例(renderer 驱动的 JSON IR):--- [`examples/archify-repo.html`](examples/archify-repo.html) — 本仓库 skill → JSON IR → 渲染器流水线-- [`examples/maka-architecture.html`](examples/maka-architecture.html) — 第三方桌面 Agent 工作台 Maka--Workflow 不是通用流程图的替代品,它更偏“技术沟通图”:有泳道、有语义颜色、有主路径和异步/审批/观测路径。比如:+### 1. 安装-```-用 archify 画一个 workflow:-用户提交请求 -> Agent 规划 -> 需要审批时进入 Approval Gate -> 调工具 -> 记录 trace -> 返回结果+```bash+npx skills add tt-a1i/archify -g```-本仓库里有一个可打开的示例:[`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html)。+这条命令通过开源的 [`skills` CLI](https://github.com/vercel-labs/skills) 为支持的 Agent 安装 Archify。---Sequence 用来解释更细的交互顺序,比如:+如果只想临时体验,不做永久安装:-```-用 archify 画一个 sequence diagram:-用户打开页面,前端请求 API,API 校验 JWT,读取 Redis,缓存未命中则查 Postgres,返回结果并写入 trace。+```bash+npx skills use tt-a1i/archify@archify --agent codex```-示例:[`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html)。+需要时可以把 `codex` 换成 `claude-code` 或 `opencode`。-+### 2. 先画一个边界清楚的视图-Data Flow 适合解释“数据资产怎么走”,比如:+不要一开始就要求一张图解释整个仓库。先从 Overview 开始:-```-用 archify 画一个 data flow:-Web 和 Mobile 上报埋点,Edge API 收集事件,Consent Gate 过滤 PII,Kafka 承接事件流,-Warehouse 存分析表,Feature Store 做每日特征,Dashboard 和 ML Model 消费下游数据。+```text+分析这个仓库,然后使用 archify 生成一张高层运行时架构图。+只保留 8–12 个核心组件,突出一条主要请求或数据路径,并标出外部依赖与信任边界。+辅助信息放进说明卡片,不要继续增加连线。```-示例:[`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html)。+如果只想解释一条调用链:---Lifecycle 用来解释“对象状态怎么变”,比如:--```-用 archify 画一个 lifecycle diagram:-Agent Run 从 Queued 进入 Planning,再进入 Executing 和 Reviewing。需要人工确认时进入-Needs Approval,缺少输入时进入 Blocked;工具失败可以 Failed 后重试,用户取消进入 Cancelled,-超时进入 Expired,成功则进入 Completed。+```text+使用 archify 画出这条登录流程:Browser -> Web App -> API -> JWT 校验 ->+Redis Session 查询 -> PostgreSQL 回源。把缓存未命中作为次要路径。```-示例:[`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html)。+### 3. 在对话中细调-+只要当前会话里仍保留源 JSON,就可以继续说:`增加 Redis`、`把鉴权移到左侧`、`突出回滚路径`。-## 版本演进--Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了位图升采样 bug,所有光栅导出改为最高 4× 原生渲染。**2.4** SVG 导出升级成双主题自持版。**2.5** 加入 workflow / sequence / data-flow / lifecycle 四种渲染器、Mermaid 输入指引、CJK-aware 文本测量、golden 测试和 CI。**2.6** 把 architecture 模式也升级到 schema + layout 校验。**2.7** 强化 workflow:phase header、group、exception lane、mainPath 主路径 lint、同泳道正交连线,以及生成后 HTML/SVG 检查器。**2.8** 加入按需 trace 动效,并拒绝 workflow 连线穿过无关节点。**2.9** 加入统一 CLI(`bin/archify.mjs`)和真实仓库 architecture 示例。**2.10** 加入 validator 修复建议、architecture grid(`row`/`col`)和 `archify inspect` 布局 JSON。--| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 | 2.8 | 2.9 | 2.10 |-|---|---|---|---|---|---|---|---|---|---|---|---|---|-| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 同 | 同 | 同 |-| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 | 同 | 同 | 同 | 同 | 同 | 同 |-| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 | **浅色导出泳道配色修复** | 同 | 同 | 同 | 同 | 同 |-| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)| 同(泳道配色修复)| 同 | 同 | 同 | 同 | 同 |-| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(最高 4×)| 同 | **Safari 修复** | 同 | 同 | 同 | 同 | 同 |-| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 | 同 | 同 | 同 | 同 | 同 | 同 |-| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 | 同(+ 菜单 a11y 修复)| 同 | 同 | 同 | 同 | 同 |-| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 | 同 | 同 | 同 | 同 | 同 | 同 |-| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 | **+ CJK 字体回退** | 同 | 同 | 同 | 同 | 同 |-| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 | 同 | 同 | 同 | 同 | 同 | 同 |-| 类型化渲染器 + schema 校验 | — | — | — | — | — | — | workflow / sequence / data-flow / lifecycle | **+ architecture** | 同 | 同 | 同 | 同 |-| Workflow 结构辅助 | — | — | — | — | — | — | 泳道 + 路由连线 | 同 | **phase、group、exception lane、mainPath lint** | **连线穿节点 guard** | 同 | 同 |-| 生成后 artifact 检查 | — | — | — | — | — | — | — | — | **✓** | 同 | 同 | 同 |-| Trace 动效 | — | — | — | — | — | — | — | — | — | **按需开启** | 同 | 同 |-| 统一 CLI | — | — | — | — | — | — | — | — | — | — | **✓** | 同 |-| 真实仓库 architecture 示例 | — | — | — | — | — | — | — | — | — | — | **✓** | 同 |-| Architecture grid + layout inspect | — | — | — | — | — | — | — | — | — | — | — | **✓** |-| Validator 修复建议 | — | — | — | — | — | — | — | — | — | — | — | **✓** |--## 快速上手--### 1. 一条命令安装--全局安装 Archify,然后按提示选择你使用的 agent:+最终得到的是一个可直接在现代浏览器中打开的 HTML 文件,并可导出 PNG、JPEG、WebP 或 SVG。-```bash-npx skills add tt-a1i/archify -g-```+## 图表类型-想先试用、不做常驻安装?下面这条命令会用 skill 的临时副本启动 Codex:+先确定你想回答的问题,再选择对应视图:-```bash-npx skills use tt-a1i/archify@archify --agent codex-```+| 类型 | 最适合 | Prompt 中应包含 |+|---|---|---|+| **Architecture** | 组件、服务、存储和系统边界 | 范围、核心组件、主要路径 |+| **Workflow** | CI/CD、审批、工具调用、runbook | 参与者、顺序、分支、异常 |+| **Sequence** | API 调用、缓存回源、鉴权和异步链路 | 调用方、被调用方、返回和时序 |+| **Data Flow** | 数据管线、血缘、PII 和下游消费 | 来源、转换、存储、敏感边界 |+| **Lifecycle** | 状态机、等待、重试和终态 | 状态、事件、重试与取消路径 |-把 `codex` 换成 `claude-code` 或 `opencode`,即可启动对应 agent。这些命令来自开源的 [`skills` CLI](https://github.com/vercel-labs/skills)。+Architecture 示例:-### 2. 复制一条 prompt+- [`examples/web-app.html`](examples/web-app.html) — 精简 SaaS 架构+- [`examples/archify-repo.html`](examples/archify-repo.html) — Archify 的 Skill → JSON IR → Renderer 流水线+- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — 显式 `row` / `col` 网格布局+- [`examples/maka-architecture.html`](examples/maka-architecture.html) — 第三方桌面 Agent 工作台-**梳理真实仓库:**+Workflow 使用泳道、清晰主路径和克制的次要分支。-```text-分析这个代码仓库,然后用 archify 生成一张架构图,展示运行时组件、数据流、外部依赖和信任边界。-```+-**解释请求链路:**+Sequence 聚焦一段随时间展开的交互。-```text-用 archify 画出这条登录链路:浏览器 -> Web App -> API -> JWT 校验 -> Redis 会话查询 -> PostgreSQL 回退。清楚标出缓存未命中路径。-```+-**展示交付流程:**+Data Flow 明确表现数据移动、转换以及敏感边界。-```text-用 archify 生成一张 CI/CD 工作流图:pull request -> 测试 -> 审批门 -> 构建镜像 -> 部署 staging -> 冒烟测试 -> 部署 production;失败时走回滚路径。-```+-发布版 skill 已内置 standalone Schema validator,安装或临时试用后即可直接 render,无需执行 `npm install`,也没有运行时依赖。+Lifecycle 区分正常进展、等待态、重试路径和终态。-### 3. 在对话中迭代+-继续提出明确的小改动,例如「加一个 Redis」「把鉴权移到左边」「高亮回滚路径」。Archify 会交付一个可在任意浏览器打开的单文件 HTML,并可导出 PNG、JPEG、WebP 或 SVG。+## 为什么用 Archify-### 其他安装方式+- **用布局判断代替通用自动布局** —— Agent 根据要讲的故事决定层级、间距、线路和视觉重点。+- **Typed JSON IR** —— 五种图都由对应 Schema 和 Renderer 驱动。+- **交付前验证** —— Schema、布局、HTML 和 SVG 检查会尽早发现结构错误和明显的可读性问题。+- **便于分享** —— 一个 HTML 文件即可打开,无需服务器或前端框架;外部字体不可用时会使用本地字体。+- **语义技术标签** —— `postgres`、`redis`、`aws.lambda`、`github-actions` 等名称会参与视觉分类,不需要沉重的图标运行时。-Archify 打包成标准 agent skill 目录(`archify/SKILL.md`),同一个 [`archify.zip`](archify.zip) 可以用于 Claude、Codex CLI 和 opencode。+Archify 不是通用绘图编辑器,也不是 Mermaid 换肤工具。它的目标是把技术意图编译成适合沟通的成品图。-**Claude.ai:**-1. 下载 [`archify.zip`](archify.zip)-2. 进入 **Settings → Capabilities → Skills**-3. 点 **+ Add**,上传 zip-4. 打开开关+## 安装方式-+推荐直接使用:-**Claude Code CLI:**```bash-# 全局(所有项目可用)-unzip archify.zip -d ~/.claude/skills/--# 或者仅当前项目-unzip archify.zip -d ./.claude/skills/+npx skills add tt-a1i/archify -g```-**Codex CLI:**-```bash-# 全局(所有项目可用)-unzip archify.zip -d ~/.agents/skills/+同一个 [`archify.zip`](archify.zip) 也可以手动安装:-# 或者仅当前项目-unzip archify.zip -d ./.agents/skills/-```--**opencode:**-```bash-# 全局(opencode 原生目录)-unzip archify.zip -d ~/.config/opencode/skills/+| 使用方式 | 安装位置或方法 | 能力 |+|---|---|---|+| **Claude Code** | `~/.claude/skills/` 或 `.claude/skills/` | 完整 Renderer + 校验流程 |+| **Codex CLI** | `~/.agents/skills/` 或 `.agents/skills/` | 完整 Renderer + 校验流程 |+| **opencode** | `~/.config/opencode/skills/`、`.opencode/skills/` 或 `.agents/skills/` | 完整 Renderer + 校验流程 |+| **Claude.ai** | 在 Settings → Capabilities → Skills 上传 `archify.zip` | 取决于沙箱是否允许执行 Node.js |+| **Project Knowledge** | 把 `archify.zip` 上传到项目知识库 | 仅 Prompt 驱动的 Architecture 模式 |-# 或者仅当前项目-unzip archify.zip -d ./.opencode/skills/+Claude.ai 的 Skills 上传入口:-# 也可以复用上面 Codex 的通用 agent 目录-unzip archify.zip -d ~/.agents/skills/-```+-renderer 驱动的图在交付前会走一个小质量闭环:+手动安装就是把压缩包解压到对应目录。分发包已包含独立校验器,不需要执行 `npm install`。-| 步骤 | 做什么 |-|---|---|-| **生成 JSON IR** | agent 先写 architecture / workflow / sequence / dataflow / lifecycle 的类型化描述,而不是直接手改最终 SVG。 |-| **Validate** | 内置 standalone validator 检查 JSON Schema,无需安装运行时依赖。 |-| **Render** | 类型化渲染器生成单文件 HTML/SVG。 |-| **Check artifact** | 生成后检查器拦截 malformed SVG、非有限坐标、误生成的两点斜线箭头、穿过图例的连线。 |-| **Iterate** | 修复尽量落在 JSON IR 或语义 class 上,局部调整不需要整张图从头生成。 |+## 工作原理-也可以直接运行最终 artifact 检查:+Renderer 驱动的图会经过一条简短、可检查的流水线:-```bash-node scripts/check-render-output.mjs output.html-```+| 步骤 | 发生什么 |+|---|---|+| **生成 JSON IR** | Agent 先生成类型化描述,而不是直接修改最终 SVG。 |+| **校验** | 内置独立校验器检查 Schema,无需安装运行时依赖。 |+| **渲染** | 对应 Renderer 生成 HTML/SVG。 |+| **检查** | 布局和 Artifact 检查发现无效坐标、损坏 SVG 和不安全线路。 |+| **迭代** | 修改集中在 JSON IR,尽量保持无关结构稳定。 |-内置 CLI 对这些 renderer / checker 命令做了一层统一包装:+从仓库源码运行 CLI:```bash+cd archifynode bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demo-node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json workflow.html+node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.htmlnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json-node bin/archify.mjs check workflow.html+node bin/archify.mjs check /tmp/workflow.htmlnode bin/archify.mjs examples```-渲染器生成的图也可以按需开启轻量动效,适合 demo 或演示场景:+演示场景可以选择开启轻量 Trace 动画:```json{ "meta": { "title": "Release Flow", "animation": "trace" } }```-Trace animation 直接运行在生成的 HTML/SVG 里:箭头按顺序流动,节点轻微 pulse;用户开启 `prefers-reduced-motion` 时会自动禁用运动。默认不写 `animation`,输出仍是静态图。+动画会遵循 `prefers-reduced-motion`。不设置 `animation` 时保持静态。-**Claude.ai Projects:**-把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。+## 使用生成结果-三种安装方式的能力差异:+在现代浏览器中打开 HTML,右上角提供两个入口:-| 安装方式 | 能力 |-|---|---|-| **Claude Code** | 完整 —— 可运行类型化渲染器 + schema 校验 |-| **Codex CLI** | 完整 —— 安装到 `~/.agents/skills/` 或 `.agents/skills/` |-| **opencode** | 完整 —— 安装到 `.opencode/skills/`、`.agents/skills/` 或其他支持的 skills 目录 |-| **Claude.ai 上传 zip** | 通常可用 —— 取决于沙箱是否允许执行 Node.js |-| **Project Knowledge** | 仅架构模式 —— 不执行代码,纯 prompt 驱动 |+- **Theme** —— 切换深色和浅色,快捷键 <kbd>T</kbd>。+- **Export** —— 复制 PNG,或下载 PNG、JPEG、WebP、SVG,快捷键 <kbd>E</kbd>。-## 用生成的 HTML--浏览器打开文件,右上角会有两个按钮:--- **主题按钮**(Dark / Light)—— 一键切换,持久化保存。快捷键 <kbd>T</kbd>。-- **Export 菜单** —— 五个操作:复制到剪贴板 + 4 种格式下载。快捷键 <kbd>E</kbd>。--### Export 菜单--| 操作 | 做什么 |+| 格式 | 适合 ||---|---|-| **Copy to clipboard** | 当前图以 PNG 格式直接进系统剪贴板,粘贴到 Slack / Notion / 飞书 / GitHub / Figma |-| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充(无透明);PNG 保留透明度 |-| **Download SVG** | 矢量导出,所有样式内联,**双主题自持**。内嵌了 dark + light 两套 CSS 变量 + `@media (prefers-color-scheme)` 规则 —— 同一个 `.svg` 贴到 GitHub README / 博客,读者切深浅色图自己跟着切。可以在 Figma / Illustrator 里继续编辑。无损缩放 |--所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在**最高 4× 源分辨率**下原生光栅化;超大图会自动降到 3× / 2× 以避开浏览器 canvas 上限。序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。+| **复制 PNG** | 飞书、Slack、Notion、GitHub 评论和快速评审 |+| **PNG / JPEG / WebP** | 演示文稿、文档、网站和印刷 |+| **SVG** | README、博客、Figma、Illustrator 和无损缩放 |-没有倍数选择器 —— 永远选择当前浏览器能稳定生成的最高清晰度。+位图会以浏览器允许的最高安全分辨率原生渲染,最高 4×。图太大时会自动降到 3× 或 2×,避免超过 Canvas 限制。-### 键盘快捷键+导出的 SVG 同时包含深色、浅色变量和 `prefers-color-scheme`,因此同一个文件可以跟随读者的系统主题。-- 任何位置按 <kbd>T</kbd> —— 切换主题-- 任何位置按 <kbd>E</kbd> —— 打开 Export 菜单-- 菜单里 <kbd>↑</kbd> <kbd>↓</kbd> —— 上下选项-- <kbd>Home</kbd> / <kbd>End</kbd> —— 跳到第一 / 最后一项-- <kbd>Enter</kbd> / <kbd>Space</kbd> —— 触发当前项-- <kbd>Esc</kbd> —— 关闭菜单+常用 URL 参数:-### URL 参数+- `?theme=light` 或 `?theme=dark` —— 固定初始主题。+- `?openExport=1` —— 加载后自动打开导出菜单。-- `?theme=light` 或 `?theme=dark` —— 强制启动主题(确定性截图、分享链接、文档嵌入场景)-- `?openExport=1` —— 页面加载时自动展开 Export 菜单(演示 / 文档截图)+WebP 和剪贴板能力取决于浏览器。外部字体不可用时,HTML 会使用本地字体 fallback。-### 注意事项+## Prompt 模板-- **WebP 兼容性**:依赖浏览器的 canvas 编码器。老版 Safari 不支持时,菜单项会变灰不可选。PNG 和 JPEG 通用。-- **剪贴板支持**:图片复制需要 `ClipboardItem` + `navigator.clipboard.write`(Chromium、Firefox 127+、Safari 16+)。不支持时 Copy 选项变灰。-- **导出字体**:光栅图会使用系统等宽字体回退(`ui-monospace` / Menlo / Consolas),因为沙箱图像渲染上下文拿不到 Google Fonts。本机装了 JetBrains Mono 会自动用上,完全像素级一致。+**仓库概览**-## 常用 prompt--**Web 应用:**-```-用 archify 画一张架构图:-- React 前端-- Node.js/Express API-- PostgreSQL 数据库-- Redis 缓存-- JWT 鉴权+```text+梳理这个仓库的运行时架构,最多保留 12 个核心组件。+展示主要请求路径、外部系统和信任边界,把实现细节放进说明卡片。```-**AWS Serverless:**-```-用 archify 画:-- CloudFront CDN-- API Gateway-- Lambda(Node.js)-- DynamoDB-- S3 存静态资源-- Cognito 做鉴权-```+**CI/CD Workflow**-**微服务:**-```-用 archify 画一张微服务架构图:-- React Web + 移动端-- Kong API Gateway-- 用户服务(Go)、订单服务(Java)、商品服务(Python)-- PostgreSQL、MongoDB、Elasticsearch-- Kafka 做事件流-- K8s 做编排+```text+画一张 CI/CD workflow:pull request -> tests -> approval -> build image ->+staging -> smoke test -> production。把 rollback 画成次要失败路径。```-**数据流 / 埋点分析:**-```-用 archify 画一个 data flow:-- Web App 和 Mobile SDK 产生 clickstream events-- Edge API 收集事件-- Consent Gate 过滤身份信息和 PII-- Kafka/Event Stream 承接 accepted events-- Warehouse 存 normalized facts-- Feature Store 每日生成 feature vectors-- Dashboards 和 ML Model 消费下游数据-```+**数据血缘**-**状态机 / 生命周期:**-```-用 archify 画一个 lifecycle diagram:-- 任务从 Queued 开始-- Planning 生成计划-- Executing 调用工具-- Reviewing 做质量检查-- Needs Approval 和 Blocked 是等待态-- Failed 可重试,Cancelled / Expired / Completed 是终态+```text+画一张从 Web、Mobile 事件经过 Consent Gate、Kafka、Warehouse、Feature Store,+最终到 Dashboard 和 ML 消费方的数据流图,并明确标出 PII 边界。```-## 语义配色+## 参考-| 类型 | 颜色 | 用途 |-|---|---|---|-| Frontend | 青色 | 客户端 / UI / 终端设备 |-| Backend | 翠绿 | 服务 / API / 后台进程 |-| Database | 紫色 | 数据库 / 存储 / AI/ML |-| Cloud / AWS | 琥珀 | 托管云服务 / 基础设施 |-| Security | 玫红 | 鉴权 / 安全组 / 加密 |-| Message Bus | 橙色 | Kafka / RabbitMQ / SNS / 事件总线 |-| External | 灰色 | 第三方 / 通用外部系统 |--每种颜色在深色 / 浅色主题下都有配套取值,切主题会同步切换。--### 语义技术标签+语义标签会参与颜色和分组:-Archify 不是要内置完整 AWS / Azure / GCP 图标运行时。它把技术名和可选标签当成语义提示,用来辅助配色、分组和文案:--| 标签示例 | 视觉类别 |+| 示例 | 类别 ||---|---|-| `react`、`nextjs`、`ios`、`android`、`browser` | Frontend |-| `node`、`go-service`、`python-worker`、`api-gateway` | Backend |-| `postgres`、`mysql`、`redis`、`s3`、`bigquery`、`snowflake` | Database / storage |-| `aws.lambda`、`aws.cloudfront`、`gcp.pubsub`、`azure.functions`、`kubernetes` | Cloud / infrastructure |-| `auth0`、`cognito`、`oauth`、`vault`、`security-group` | Security |-| `kafka`、`rabbitmq`、`sns`、`sqs`、`nats` | Message bus |-| `stripe`、`github-actions`、`openai`、`anthropic`、`slack` | External |--当具体技术栈重要时,可以在 prompt 或 JSON IR 里写这些标签。最终输出仍然是自持 HTML/SVG;标签只增强语义样式和布局,不引入重型图标依赖。+| `react`、`nextjs`、`ios`、`browser` | 前端 |+| `node`、`go-service`、`python-worker`、`api-gateway` | 后端 |+| `postgres`、`redis`、`s3`、`bigquery`、`snowflake` | 数据和存储 |+| `aws.lambda`、`gcp.pubsub`、`azure.functions`、`kubernetes` | 云与基础设施 |+| `auth0`、`oauth`、`vault`、`security-group` | 安全 |+| `kafka`、`rabbitmq`、`sqs`、`nats` | 消息系统 |+| `stripe`、`github-actions`、`openai`、`slack` | 外部系统 |-## 实现细节+Renderer 输入请查看 [Schema 说明](archify/schemas/README.md),版本历史请查看 [CHANGELOG.md](CHANGELOG.md)。-- **样式模型**:`:root` + `[data-theme="light"]` 上的 CSS 变量;SVG 元素引用语义 class(`c-frontend`、`t-muted`、`a-emphasis` 等)。切换 `<html>` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。-- **导出流水线**:克隆 SVG,内联 host `<style>`,解析当前主题变量并写入 clone 的 `:root` 规则,然后用 `XMLSerializer` 序列化。光栅格式下,clone 的 `width`/`height` 被设为 `4 × viewBox`,浏览器按目标分辨率原生光栅化矢量;canvas 尺寸对齐 clone 后按自然大小绘制(无位图升采样),`toBlob(mime)` 生成文件。JPEG 会显式补背景色(无 alpha)。如果目标分辨率超过浏览器 canvas 上限,自动降到 3× 或 2×。-- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 19 KB 嵌入 JS。生成的 HTML 和发布版 renderer 都是零运行时依赖 —— 无构建步骤、无 JS 框架、无服务端。-- **生成后检查**:`bin/archify.mjs validate`、渲染器布局检查和 `scripts/check-render-output.mjs` 会在交付前检查生成的图:schema 合法、SVG 坐标有限、没有误生成两点斜线箭头、箭头线段不穿过图例。-- **浏览器支持**:任何主流浏览器(Chrome、Safari、Firefox、Edge)。WebP 导出需要 canvas 支持 `image/webp`。+## 当前状态与路线图-## 致谢+Archify 2.10 的五种 Renderer 模式都已经使用 Typed JSON IR。接下来的重点是稳定局部修改、改善布局诊断,并让生成结果更容易检查和分享。-Archify 是 [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator)(MIT,v1.0)的 fork 重写,原作者 [Cocoon AI](mailto:[email protected])。原版精致的视觉语言 —— 配色、网格背景、摘要卡片布局、JetBrains Mono 字体 —— 完整保留。视觉设计功劳归属原作者。+规划和产品边界请查看 [ROADMAP.md](ROADMAP.md)。自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不是目标。-Archify 2.x 贡献:--- 模板重构为 CSS 变量主题系统(深色 + 浅色)-- 主题切换 + `localStorage` 持久化 + `prefers-color-scheme` 默认-- 内置 PNG / JPEG / WebP / SVG 导出菜单 + 复制到剪贴板-- 4× 原生光栅化(修复升采样导致的模糊)-- SVG 导出双主题自持(单文件跟随宿主 `prefers-color-scheme`)-- 键盘导航 + 可访问性语义-- 打印样式表 + 本地字体回退-- Architecture、workflow、sequence、data-flow、lifecycle 五类渲染器 + schema 校验-- 生成后 artifact 检查,约束最终 HTML/SVG 质量-- 统一 CLI(`bin/archify.mjs`):render / validate / check / examples-- 真实仓库 architecture 示例(`archify-repo`、`maka-architecture`)-- 更新后的 `SKILL.md` 引导 Claude 使用 class 化、可主题化的画图方式--两个项目都是 MIT 协议。--## 路线图--详见 [ROADMAP.md](ROADMAP.md)。+## 致谢-下一站是 **v3.0 — JSON IR 稳定迭代**:引入极简 `diagram.json` 中间格式,让 Claude 做局部坐标修改时不会漂移无关组件,同时支持 `git diff` 友好和 theme/palette 不重渲染。+Archify 基于 Cocoon AI 的 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 进行 Fork 和重写。-> **关于 Mermaid 输入:** 已实现 —— `SKILL.md` 现在有专门的「Mermaid as an Input Dialect」章节,把 flowchart / sequenceDiagram / stateDiagram 映射到 workflow / sequence / lifecycle。注意走的是 prompt 而不是 parser:经实验验证(auto-layout + archify CSS 并不比原生 Mermaid 好看多少),自动解析器路线已砍掉。archify 的美学核心是 Claude 的布局判断,不是 CSS —— 贴 Mermaid 代码,Claude 从零布局出 archify 风格图。->-> 原 v2.4 / v2.5 计划(`?exportScale=N`、色盲调色板、分享链接)也已砍掉。理由见 [ROADMAP「Not planned」段落](ROADMAP.md#not-planned)。+原项目的视觉语言仍归功于 Cocoon AI。Archify 2.x 在其基础上增加了主题、导出、Typed Renderer、校验、无障碍支持和统一 CLI。两个项目都采用 MIT License。## License-[MIT](LICENSE) —— 自由使用、修改、再分发。+[MIT](LICENSE) —— 可以自由使用、修改和分发。## 参与贡献-欢迎 issue、PR、分享你画的图。+欢迎提交 Issue、Pull Request 和分享生成的图。报告产物问题时,请尽量附上 Prompt、图表类型和 Archify 版本。