# How Does Archify Work? A Deep Dive into the 5-Stage Diagram Pipeline > Discover how Archify works. This article details the 5-stage pipeline that transforms natural language into validated, interactive architecture diagrams, using a typed JSON intermediate representation. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: deep-dive - Published: 2026-09-12 --- **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. ```bash 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. ```bash 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. ```bash 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. ```bash 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/delta.html), highlighting added, removed, changed, or moved components between architecture versions. ```bash 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)**: Schema definitions for each diagram type, establishing the contract for valid JSON IR. - **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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.