Archify: AI Agent Skill Generates Validated Interactive Architecture Diagrams from Code

Archify is an open-source Agent Skill (MIT licensed, v2.14.0) that turns a natural-language description of a system or a code repository into a professional, interactive technical map. Installation is a single command: npx skills add tt-a1i/archify -g. Once installed, telling an AI agent "使用 archify 分析这个仓库的架构" triggers fully automated analysis, layout, validation, and rendering — no JSON Schema or renderer knowledge required.

Supported Diagram Types

Archify offers five diagram types, each tailored to a specific architectural concern:

Architecture — system architecture, component relationships, deployment boundaries

Workflow — CI/CD pipelines, approval flows, tool invocation chains

Sequence — API calls, cache fallback, authentication sequences

Data Flow — data pipelines, lineage, downstream consumers

Lifecycle — state machines, retries, waits, terminal states

If unsure which type fits, the CLI guide answers questions like

node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求用哪种图"

and recommends Sequence for that scenario.

Hands-On Test: Spring Boot Project Analysis

The author tested Archify on lingma-test, a Spring Boot project integrating Alibaba Cloud Lingma API. The project contains Controller, Service, API Client, HTTP utility, global exception handling, Swagger config, and an external dependency. A single instruction — "使用 archify 分析项目，画图" — caused the agent to:

Read pom.xml for tech stack

Scan Java sources for call relationships

Generate an Architecture-type JSON spec defining 10 component nodes, 2 boundary domains, 10 connections, and 3 summary cards

Node types determine visual style; connections carry semantic labels such as HTTP GET, @Autowired, doGetWithParams. The JSON then passes through a validate step. The first validation reported 4 label-overlap errors; the agent fixed only three labelDy offsets on the diagnosed connections, and the second validation passed — demonstrating precise, targeted repair without full regeneration. The final deliver step produced a ~640 KB standalone HTML containing complete SVG and interaction logic. The resulting diagram shows a clear left-to-right main chain from client through Controller, Service, ApiClient, HttpClientUtil to the external Lingma API, with cross-cutting concerns (Swagger UI, GlobalExceptionHandler) connected via dashed lines, and two boundary domains delineating application scope and token authentication scope.

Validation Pipeline: The Core Differentiator

Archify's validation pipeline separates it from general diagramming tools. The agent's first artifact is Typed JSON (an intermediate representation), not HTML. Each diagram type has a dedicated JSON Schema. Validation runs in two stages:

Schema validation — ensures structural correctness

Layout validation — ensures labels don't overlap, edges don't cross unrelated nodes, segment lengths meet minimum thresholds

Two validation tiers exist: standard and showcase. Showcase demands all 9 checks pass, including single SVG output, orthogonal arrow routing, label clearance distance, relationship crossing count, and container border continuity. On failure, validate returns structured diagnostics: the offending object, measured values, and supported fix strategies. The agent applies fixes and re-validates; only after passing does deliver atomically replace the output file. Previous validated files are never overwritten, guaranteeing no half-baked output reaches the user.

Interactive Viewer Features

The generated HTML is a full-featured interactive viewer: / — search and focus nodes R — probe directed paths between two nodes L — compare semantic roles (e.g., backend ↔ database traffic) P — play guided story; if views are defined in JSON, the viewer steps through chapters highlighting nodes and relationships, ideal for technical presentations T — toggle dark/light theme E — export PNG, SVG, WebM, and a 1200×630 share card

Share cards are practical: after tracing a path, exporting a Route Share Card yields a 1200×630 PNG with the path highlighted and surrounding context preserved, ready for READMEs or docs. Deep links like #focus=controller or #route=client~lingma-api open the viewer pre-focused on the target element.

Architecture Delta for PR Reviews

A standout feature is Architecture Delta, which compares two architecture specs and renders a three-column Before / Delta / After view. It precisely marks added components, removed connections, and changed relationships — no inferred impact or risk analysis, just the author's explicit changes. The command is:

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

This read-only diff is valuable during PR reviews to visualize architectural impact before merge. The design is deliberately conservative and reliable; AI can further analyze the diff if desired.

Conclusion and Resources

Archify solves a concrete pain point: eliminating manual diagram drawing while ensuring accuracy and visual quality. A conversational description yields a validated, interactive technical map shareable as a single HTML file — no extra software needed. Highlights include showcase-grade validation, a feature-rich interactive viewer (search, path tracing, role comparison), and Architecture Delta for PR reviews. As the author emphasizes, Archify is not a general drawing editor nor a Mermaid skin; it transforms technical intent into a communication-ready artifact.

GitHub: https://github.com/tt-a1i/archify (MIT). The Proof Lab page hosts 11 validated example scenarios for preview, and an interactive scenario guide helps choose the right diagram type. For developers who regularly create architecture, flow, or sequence diagrams, this skill is worth installing — it delivers production-grade diagrams without leaving the chat window.