Archify: Turn Code Repositories into Interactive Architecture Diagrams

What Is Archify?

Archify is a tool that works with coding agents (Cursor, Claude Code, Codex CLI, OpenCode) to produce interactive architecture diagrams. You describe a system in natural language — for example,

用 Archify 画出 Browser -> API -> Redis -> PostgreSQL 的缓存回源过程

— and the agent writes a typed JSON intermediate representation (IR). Archify then validates that IR against a schema, checks layout and relationship constraints, and deterministically compiles it into a standalone HTML file (and SVG). The tool does not provide its own AI model or a drag‑and‑drop canvas.

Diagrams are categorized into five types:

Architecture : system components, services, databases, security boundaries.

Workflow : CI/CD pipelines, approval flows, tool calls, runbooks.

Sequence : API calls, cache‑backfill, authentication, async chains.

Data Flow : data pipelines, lineage, sensitive‑data movement, downstream consumers.

Lifecycle : state changes, retries, waits, cancellations, final results.

For existing projects, the agent can read the repository to extract core components, main call chains, external dependencies, and system boundaries. Nodes can be linked to specific files and line numbers at a fixed Git commit, allowing readers to jump back to source code for verification.

Problems Archify Solves

Traditional one‑shot SVG generation forces a full redraw whenever requirements change (e.g., add Redis, move auth to the left, highlight rollback path). Archify retains the typed JSON IR, so the agent only modifies the relevant objects. The IR passes through schema, layout, and output validation — ensuring no lines cross unrelated nodes, labels don’t overlap other edges — before a new HTML/SVG is emitted. Validation failures return machine‑readable diagnostics (object, measurements, allowed fixes), letting the agent make targeted corrections instead of guessing from a stack trace.

The end‑to‑end flow:

自然语言或代码仓库
    ↓
Agent 理解系统结构
    ↓
生成 Typed JSON IR
    ↓
Archify 校验布局与关系
    ↓
输出可交互 HTML / SVG

Archify focuses on post‑generation concerns: preserving unrelated structure during edits, running fixed checks before delivery, and keeping relationships traceable to the JSON source.

Key Highlights

Explorable Diagrams

The generated HTML includes a built‑in viewer with node search, zoom, dark/light theme toggle, and the ability to focus on a component to see its upstream and downstream paths. For example, in an e‑commerce architecture containing Web, API, cache, message queue, order service, and database, you can select Web and database to highlight only the directed paths already defined in the diagram. Semantic role comparison shows actual connections between backend services and databases; guided stories walk through predefined chapters for technical reviews or demos.

Archify only renders relationships explicitly present in the source file; connectivity in the diagram does not imply runtime impact analysis.

Pre‑Delivery Validation

Archify validates JSON schema conformance, layout issues (e.g., edges crossing unrelated nodes, labels overlapping edges), and that the output HTML/SVG functions correctly. A candidate version replaces the previous successful output only after passing all checks. With local preview enabled, an incomplete JSON modification keeps the last valid diagram on screen instead of showing a broken render. The validator checks format, geometry, and declared relationships; it cannot prove that code analysis missed components or call chains — final confirmation still requires a system‑knowledgeable human.

Architecture Diffing

For technical design or PR reviews, Archify can compare two validated architecture snapshots, producing Before, Delta, and After views. It distinguishes added/removed/moved nodes, changed relationships, and re‑routed edges. This is more effective than side‑by‑side static images for spotting the scope of a change. The diff shows only determinable differences between the two source files; it does not assess risk magnitude or decide merge readiness.

Single Portable HTML File

The final artifact is a self‑contained HTML file with no dependency on Archify hosting. It can be shared, opened locally, or embedded in documentation. Static exports include PNG, JPEG, WebP, SVG; animated path demonstrations can be exported as WebM. A 1200×630 share card is provided for READMEs, releases, or social posts. Four built‑in visual styles — Classic, Signal Flow, Blueprint, Editorial — plus dark/light themes change only appearance, not layout.

Integration with Multiple Coding Agents

Archify ships as a Skill for Cursor, Claude Code, Codex CLI, and OpenCode, and can be manually installed into Raven. A community‑maintained plugin for DeepSeek Harness (DSH) loads the Archify Skill, but it targets the Developer Preview DSH version ( @deepseek-ai/[email protected]) and bundles an Archify 2.14 snapshot (not auto‑updated to 2.16). Compatibility is not guaranteed long‑term. DSH‑generated JSON and HTML are ordinary workspace files and may not appear in the web UI’s Produced Files area; the agent should return explicit file paths. Claude.ai can accept an uploaded archify.zip, but full rendering and validation depend on the sandbox providing Node.js and file‑system access.

How to Use Archify

The renderer requires Node.js 18 or higher .

Global Skill Installation (Codex, Claude Code, Cursor, OpenCode)

npx skills add tt-a1i/archify -g

Temporary Use with Codex

npx skills use tt-a1i/archify@archify --agent codex

Example Prompts

Generate a diagram from description:

使用 Archify 画出：Browser -> API -> Redis 缓存 -> PostgreSQL 回源。

Analyze a repository and produce a high‑level runtime architecture:

分析这个仓库，然后使用 Archify 生成一张高层运行时架构图。
只保留 8～12 个核心组件，突出一条主要路径，
并标出外部依赖与信任边界。
辅助信息放进说明卡片，不要继续增加连线。

Iterative edits after the first diagram:

增加 Redis。
把鉴权模块移到左侧。
突出从 API 到数据库的缓存回源路径。

Verify Installation

node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo

DeepSeek Harness (Community Plugin)

dsh plugin --profile web add @tt-a1i/[email protected]

Requires Node.js ^22.19.0 or >=24.0.0. The plugin bundles Archify 2.14 and does not auto‑upgrade with the main repo.

Real‑World Trial: SpringAI InterviewGuide (3.1k+ Stars)

The author tested Archify on the open‑source SpringAI InterviewGuide 2.0 project (React frontend, Spring Boot API, WebSocket voice interviews, PostgreSQL, Redis Stream, object storage, external AI services). The prompt asked for 8–12 core components, main request chains, async tasks, and data‑storage relationships. The resulting diagram combined ordinary requests, RAG streaming responses, voice interviews, and async consumers on one canvas, with three detail cards at the bottom.

The same architecture data can be switched to Blueprint style without recomputing nodes or edges — only the visual theme changes, making it look more like an engineering blueprint for design reviews.

After an initial validation pass, the author manually reviewed the screenshot. The first version incorrectly wrapped the external AI provider and PostgreSQL inside the Spring Boot boundary; removing that outer frame yielded 0 errors, 0 warnings across all 9 showcase checks.

Summary

Archify sits between Mermaid and draw.io: Mermaid is quicker for throwaway flowcharts; draw.io is better for pixel‑perfect manual layout. Archify shines when a coding agent generates diagrams from system descriptions or codebases, followed by repeated edits, relationship verification, and PR‑level architecture diffing. By keeping a JSON source, running fixed pre‑delivery checks, and emitting a portable HTML file, Archify mainly saves the time spent on re‑layout, re‑drawing, and manual relationship cross‑checking.

Project URL: https://github.com/tt-a1i/archify (≈35.7K stars, 2.3K forks, MIT license).