Archify: The Agent That Draws Verified Architecture Diagrams

Why Archify now

Architecture documents are often harder to maintain than actual code. Their diagrams are hard to keep up to date after deployment, and even Mermaid text conventions become unreadable when auto-formatting breaks. Archify addresses both accuracy and shareability with just one tool.

The problems Archify solves

Archify is an open source tool that standardizes codebases and system descriptions into diagrams. Install the skill into coding agents like Cursor, Claude Code, Codex CLI, and OpenCode, then simply say "draw an architecture diagram of this repo" to receive diagrams in architecture, workflow, state, datastore, and lifecycle formats. The output is a single HTML file, enabling search, zoom, theme switching, and sharing directly within the diagram. You can verify this at the GitHub repository tt-a1i/archify.

Core features

Diagram types and supported scope

Archify supports architecture, workflow, state, datastore, and lifecycle diagrams. Each type has a clear use case, making it easy to write for issues like "login flow" or "cache miss state machine". The generation process creates a JSON IR, and bundled validators check schema, layout, routing, and label consistency before rendering HTML/SVG.

Step	Content
Generate	Agent creates typed JSON IR
Validate	Schema·layout·routing·label checks
Preview	Reload only changed parts locally
Deliver	Deliver verified artifacts to same directory
Iterate	Revise JSON and maintain scope

Before / Delta / After Comparison

This feature is useful for PR reviews or architecture change audits. By inputting JSON IRs for the baseline and changed versions, it extracts only additions, deletions, changes, moves, and renamed facts to present as Before / Delta / After. This can be executed in the repository with node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json format.

Evidence Citation Mode

By default, Archify only shows verified authored topology and does not handle randomness. If you write Evidence-backed Architecture mode, SRC n labels appear on nodes, and you can link to specific files and lines of public commits. For general artifacts, this structure is selectively attached only when documentation is necessary.

Comparison with other tools

Mermaid is a text-based diagramming notation but has limitations in automatic layout and version control is difficult. Archify treats JSON IR as the primary source, enabling diff, verification, and reuse. Also, since the output is a single HTML file, sharing and embedding are easy. You can check the live demo and guide on the project page tt-a1i.github.io/archify.

Practical Usage Points

In a Node.js environment, npx skills add tt-a1i/archify -g allows easy installation. After installation, just say "draw an architecture diagram of this repo" in natural language. Diagram Guide is available via the ? key, node search via the / key, and route tracing via the R key. Current limitations such as host sharing, automatic Mermaid export, and WYSIWYG editing are mentioned in the README.

Wrapping up

Archify is a tool that turns architecture diagrams—documents that are harder to maintain than code—into executable artifacts. Single HTML, typed JSON IR, verification pipeline, and these three strengths solve the common problems of manual diagram fading and inconsistency. If you're interested, it's good to check the example artifacts in the repository's examples/ directory or Proof Lab first.