What Is Archify and Its Primary Purpose? An AI-Powered System Mapping Tool Explained

Archify is an agent skill that transforms codebases or textual system descriptions into polished, interactive system maps through a validate-and-deliver workflow.

Archify bridges the gap between raw code understanding and visual communication. Developed as an open-source tool in the tt-a1i/archify repository, it enables AI-augmented developers to generate deterministic, auditable architecture diagrams directly from chat interfaces—without hallucinated topology or unsupported runtime claims.

How Archify Works: The Five-Step Workflow

The core engine follows a strict pipeline defined in README.md (lines 13–35). Each stage produces machine-verifiable artifacts:

1. Generate — Typed JSON Intermediate Representation

The agent parses your prompt or codebase into a strictly-typed JSON IR. This intermediate representation captures nodes, edges, trust boundaries, and evidence links as structured data rather than rendered pixels.

npx skills add tt-a1i/archify -g

This installs the skill globally for agents including Raven, Cursor, Claude Code, or OpenCode.

2. Validate — Schema and Layout Enforcement

Built-in validators in archify/SKILL.md enforce JSON schema compliance, layout rules, and routing logic. Failures return machine-readable repair receipts rather than broken diagrams (README.md, lines 98–102).

3. Preview — Local Loop with Error Recovery

A file watcher monitors the JSON source and reloads only after successful validation. If validation fails, the previous good diagram remains visible—no blank screens or partial renders (README.md, lines 16–21).

4. Deliver — Atomic Artifact Replacement

Verified outputs replace previous versions atomically. Supported formats include HTML, PNG, SVG, WebM, and share-cards—all self-contained and ready for embedding in READMEs or release notes (README.md, lines 24–29).

5. Iterate — Surgical Updates

The agent modifies specific JSON regions while preserving the rest of the diagram, enabling focused refinement without regenerating everything (README.md, lines 30–35).

Primary Purpose: Trustworthy Visual Representation

Archify exists to solve a specific problem: architecture diagrams that drift from reality or cannot be audited. Its design priorities are:

• Grounded in authored facts — Evidence links attach to exact source lines when requested
• Deterministic output — Same input produces identical JSON IR and render
• Deterministic and auditable — Every claim traceable to codepaths or explicit declarations

Target use cases include architecture reviews before PR merges, agent-driven interactive exploration (search nodes, trace reachability, compare roles), and exportable artifacts for documentation.

CLI Commands and Practical Usage

Generate a Diagram from Description

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"

The guide command in archify/bin/archify.mjs outputs both an HTML diagram and the typed JSON source (README.md, lines 58–63).

Compare Architecture Snapshots

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

The compare command produces a Before / Delta / After view highlighting added, removed, changed, and moved facts—ideal for delta reviews (README.md, lines 52–56).

Agent-Directed Generation

Use archify to create a high-level runtime architecture diagram of this repository.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.

The agent handles JSON IR generation, validation, and returns an interactive HTML file (README.md, lines 17–24).

Key Source Files and Their Roles

File	Purpose
archify/bin/archify.mjs	Main CLI entry; implements guide, validate, preview, deliver, compare
archify/SKILL.md	Formal agent contract—JSON schema, renderer expectations, validation rules
archify/schemas/README.md	Typed-JSON schema definitions for five diagram modes
examples/web-app.html	Runnable example viewer of generated web-app architecture

Summary

• Archify is an agent skill for converting codebases into interactive system maps through a validated JSON pipeline
• The primary purpose is producing trustworthy, shareable, self-contained visual representations without invented topology
• Five-stage workflow: Generate → Validate → Preview → Deliver → Iterate
• Output formats: HTML, PNG, SVG, WebM, share-cards
• Key command: archify/bin/archify.mjs with subcommands guide, compare, validate, preview, deliver

Frequently Asked Questions

What makes Archify different from other diagram generators?

Archify requires machine-validated JSON IR before any visual output, produces repair receipts on failure, and maintains evidence links to exact source lines. This eliminates drift between diagram and codebase that plagues manually maintained documentation.

Can Archify run without an AI agent?

Yes. The CLI in archify/bin/archify.mjs operates independently. You can invoke guide, validate, preview, deliver, and compare commands directly with JSON files or text descriptions.

What diagram types does Archify support?

According to archify/schemas/README.md, Archify supports five typed-JSON schema modes covering system architecture, workflow, sequence, data-flow, and lifecycle diagrams.

How does Archify handle errors during generation?

Validation failures return machine-readable repair receipts rather than partial renders. The preview loop preserves the last valid diagram while you fix the JSON source, ensuring you never present broken or misleading visuals.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}