How Does Archify Work? A Deep Dive into the 5-Stage Diagram Pipeline

Archify transforms natural language system descriptions into validated, interactive architecture diagrams through a deterministic five-stage pipeline—generate, validate, preview, deliver, and iterate—using a typed JSON intermediate representation as the single source of truth.

Archify is an open-source CLI tool in the tt-a1i/archify repository that converts textual system descriptions into share-ready technical artifacts. Unlike traditional diagramming tools that rely on manual layout manipulation, Archify employs a schema-driven pipeline where natural language inputs are first converted into a strictly typed JSON intermediate representation (IR), validated against layout rules, and then rendered deterministically into self-contained HTML, PNG, SVG, or WebM outputs.

The Five-Stage Execution Pipeline

Archify processes every diagram request through five coordinated stages implemented in archify/bin/archify.mjs.

Stage 1: Generate Typed JSON IR

The pipeline begins when an agent—not limited to the CLI, but including Cursor, Claude Code, Codex, or OpenCode—parses the natural language prompt into structured data. The output is a typed JSON IR conforming to schemas defined in archify/schemas/, representing diagram types such as Architecture, Workflow, Sequence, Data Flow, or Lifecycle. This JSON serves as the immutable contract between the generation and rendering phases.

node archify/bin/archify.mjs generate \
  "Browser -> API -> Redis cache -> PostgreSQL fallback." \
  --type architecture \
  --output my-diagram.json

Stage 2: Validate Schema and Layout Rules

Before rendering, the IR undergoes rigorous validation. Built-in validators check schema compliance, layout constraints, routing logic, and label-to-route clearance. Errors emit as machine-readable JSON containing precise diagnostics[] arrays with supportedFixes that agents can apply automatically.

node archify/bin/archify.mjs validate \
  architecture my-diagram.json \
  --quality showcase \
  --json

Stage 3: Preview During Development (Optional)

Developers can launch a loopback-only desktop session that watches the JSON file for changes. Located at 127.0.0.1, this local server accepts only validated revisions; if validation fails, the viewer retains the previous good diagram state, preventing broken renders from disrupting the workflow.

node archify/bin/archify.mjs preview \
  architecture my-diagram.json \
  /tmp/diagram.html \
  --quality showcase

Stage 4: Deliver Atomic Artifacts

The deliver stage renders the validated IR and performs an atomic file replacement. The new artifact replaces the prior version only if all quality gates pass. Use the --open flag to automatically launch the generated file in your default browser.

node archify/bin/archify.mjs deliver \
  architecture my-diagram.json \
  final.html \
  --quality showcase \
  --open \
  --json

Stage 5: Iterate with Stable Layouts

During refinement, agents update specific fields in the JSON IR while the overall layout engine maintains spatial stability. This allows rapid, targeted modifications—such as changing labels or adding nodes—without triggering complete re-layouts that would destroy visual continuity.

Core Technical Concepts

Understanding how Archify works requires familiarity with four architectural pillars implemented throughout the codebase.

Typed JSON IR as Source of Truth

Every diagram type maintains a strict schema in archify/schemas/. The JSON IR is the single artifact passed between generation, validation, and rendering stages, ensuring consistency across the pipeline.

Deterministic Rendering

Given identical JSON input, Archify produces bit-for-bit identical HTML, SVG, or PNG outputs. This determinism makes artifacts version-stable and share-ready across teams.

Atomic Validation

Both validate and deliver commands emit a single JSON diagnostics object. Rather than failing silently or allowing partial renders, the system applies only suggested fixes from supportedFixes, preventing "guesswork" retries.

Interactive Zero-Dependency Viewer

Generated HTML files include a lightweight viewer (viewer/*.js files such as viewer/semantic-radar.js) that provides keyboard shortcuts for focus modes, routing visualization, lensing effects, export controls, and guided story navigation—all without external dependencies.

Advanced Operations: Architecture Delta Comparison

Beyond single diagram generation, Archify supports differential analysis through the compare command. This operation accepts two JSON IR snapshots (base and head) and produces delta.html, highlighting added, removed, changed, or moved components between architecture versions.

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

Key Source Files in the Repository

The following files constitute the core implementation referenced throughout this guide:

• archify/bin/archify.mjs: The CLI entry point implementing all commands (generate, validate, preview, deliver, compare, guide).
• archify/schemas/README.md: Schema definitions for each diagram type, establishing the contract for valid JSON IR.
• archify/SKILL.md: The formal Skill contract specifying input/output expectations for agent integration.
• viewer/*.js: Browser-side interactive components handling navigation, export, and guided stories.

Summary

• Archify converts natural language to diagrams via a five-stage pipeline: generate, validate, preview, deliver, and iterate.
• The typed JSON IR in archify/schemas/ serves as the immutable contract between stages.
• Deterministic rendering ensures identical inputs produce identical HTML, SVG, or PNG outputs.
• The zero-dependency CLI at archify/bin/archify.mjs supports Node 22+ without external requirements.
• Atomic validation prevents broken artifacts from reaching production through machine-readable diagnostic gates.

Frequently Asked Questions

What input formats does Archify accept?

Archify accepts natural language descriptions as plain text arguments to the generate command. The tool then converts these descriptions into a typed JSON intermediate representation. For programmatic use, agents can pass pre-structured JSON IR directly to the validate or deliver stages.

Is Archify dependent on specific AI models or cloud services?

No. While Archify accepts output from agents like Cursor, Claude Code, Codex, or OpenCode, the core CLI operates as a zero-dependency Node.js application (version 22+). The validation, rendering, and preview logic executes locally without requiring API calls or external services.

How does Archify ensure diagram consistency across team members?

Archify achieves consistency through deterministic rendering and atomic validation. Because identical JSON IR inputs always produce identical visual outputs, teams can version-control the JSON source files in archify/schemas/ rather than binary images. The validation stage enforces layout rules that prevent subjective styling variations.

Can I export diagrams to formats other than HTML?

Yes. While the primary output is self-contained HTML with an interactive viewer, the deliver command supports additional export formats including PNG, SVG, and WebM. These artifacts render identically to the HTML version but suit different publication contexts, such as documentation or presentation slides.

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