English · 简体中文
Turn plain-English system descriptions into polished architecture, workflow, sequence, data-flow, and lifecycle diagrams — directly in chat.
Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a self-contained HTML diagram that opens in any modern browser, switches between dark and light themes, supports focused exploration, and exports clean static or motion assets.
- Five diagram types — architecture, workflow, sequence, data flow, and lifecycle
- Three live visual presets — author a default, then try
classic,signal-flow, orblueprinton the same topology - Explore real topology — find nodes, inspect relationships, trace routes, compare roles, and play guided stories
- Motion is optional — output stays static unless
meta.animation: "trace"is explicitly enabled - Portable exports — copy PNG or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM
- Typed and checked — JSON IR, bundled schema validation, default semantic safety gates, and opt-in composition profiles
- Self-contained output — one shareable HTML file with no viewer runtime dependency
- Built for agent workflows — install once, then create and refine diagrams through conversation
Project page · Scenario guide · Proof Lab
npx skills add tt-a1i/archify -gThen ask your agent: Use archify to map this repository's runtime architecture.
These are generated Archify artifacts, not product mockups. Click a frame to open its live, shareable state.
Three real generated artifacts. Signal Flow · Blueprint · Classic · open the interactive Proof Lab ↗
| Guided story | Route probe | Semantic lens |
|---|---|---|
 |
 |
 |
| Play one finite named chapter. | Inspect the shortest authored directed path. | Compare real traffic between semantic roles. |
The Proof Lab contains all 11 checked-in scenarios, their JSON sources, named views, and validation receipts.
Same diagram, two themes, one click to switch:
| Dark | Light |
|---|---|
 |
 |
The Export menu copies PNG to the clipboard and downloads static or motion formats:
Open examples/web-app.html locally to try the complete viewer.
npx skills add tt-a1i/archify -gTo try it without a permanent install:
npx skills use tt-a1i/archify@archify --agent codexReplace codex with claude-code or opencode when needed. The packaged archify.zip also works without npm install.
Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.
For a focused flow:
Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->
Redis session lookup -> PostgreSQL fallback. Keep the cache-miss path secondary.
Continue with focused requests such as add Redis, move auth to the left, or highlight the rollback path. Archify keeps the typed source available for targeted iteration.
| 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, consumers | Sources, transforms, stores, boundaries |
| Lifecycle | States, retries, waits, terminal outcomes | States, events, retry and cancellation paths |
Not sure which one fits? Use the interactive scenario guide, or ask the zero-dependency CLI:
node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --jsonWorkflow keeps the happy path clear across lanes:
Sequence explains one interaction over time:
Data Flow makes movement and sensitivity boundaries explicit:
Lifecycle separates progress, waits, retries, and terminal outcomes:
Architecture examples: web-app · Archify pipeline · grid placement · desktop agent
- Layout judgment over generic auto-layout — the agent chooses hierarchy, spacing, routes, and emphasis for the story.
- Typed JSON IR — every renderer-backed mode has a schema and reproducible source.
- Validation before delivery — schema, layout, HTML/SVG, route, and optional showcase checks catch broken output.
- Truthful interaction — focus, routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology.
- Portable by default — the result is one HTML file; exports remain full-diagram and free of temporary viewer state.
Archify is not a general-purpose drawing editor or a Mermaid theme. It turns technical intent into a communication artifact.
| Step | What happens |
|---|---|
| Generate | The agent creates typed JSON IR from your description. |
| Validate | Bundled validators and layout rules check the source. |
| Render | The selected renderer produces standalone HTML and SVG. |
| Check | Artifact checks reject malformed geometry and unsafe routes. |
| Iterate | The agent updates the source while unrelated structure stays stable. |
Useful repository commands:
cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs check /tmp/workflow.htmlOptional motion and presentation styling are explicit:
{
"meta": {
"animation": "trace",
"visual_preset": "signal-flow"
}
}Omit animation for a truly static diagram. classic remains the default visual preset.
| Action | Control |
|---|---|
| Open the factual Diagram Guide | ? |
| Find and focus a semantic node | / |
| Probe a directed route and inspect its journey | R or PATH |
| Compare one or two semantic roles | L or LENS |
| Open the live overview radar | M or MAP |
| Play a guided story / change chapter | P / [ ] |
| Enter Presentation Stage | F |
| Cycle visual style / toggle theme / open Export | S / T / E |
| Zoom or reset | + / - / 0 |
Stable links can restore #focus=<id>, #relation=<id>, #route=<source>~<target>, #lens=<kind>~<kind>, and #view=<view-id>. Reader-driven motion is finite, respects prefers-reduced-motion, and never enters canonical exports.
The complete generation and viewer contract lives in archify/SKILL.md.
| 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 fallback |
Archify 2.11 includes typed IR across all five modes, three visual presets, optional finite motion, guided views, semantic exploration, shareable deep links, browser-native WebM recording, and explicit standard / showcase quality profiles.
Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.
Archify is a fork and rewrite of Cocoon-AI/architecture-diagram-generator v1.0. The original visual language remains credited to Cocoon AI; Archify 2.x adds themes, exports, typed renderers, validation, accessibility, interaction, and a unified CLI. Both projects use the MIT License.
MIT — free to use, modify, and distribute.
Issues, pull requests, and shared diagrams are welcome. For generated-output problems, include the prompt, diagram type, and Archify version. Run node scripts/build-gallery.mjs after changing bundled examples or the standalone viewer.