# How to Use Archify: A Complete Guide to Rendering System Diagrams > Master Archify with this complete guide. Learn to render interactive system diagrams from textual descriptions using this Node.js engine. Unlock clear visualizations today. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-09-12 --- **Archify is a Node.js-based rendering and validation engine that converts textual system descriptions or typed JSON intermediate representations (IR) into polished, interactive HTML/SVG diagrams through a deterministic four-stage pipeline.** Learning how to use Archify enables you to transform abstract system architectures into shareable, version-controlled visual artifacts. The tool operates as an OpenAI-compatible skill that processes structured JSON input to generate deterministic outputs, ensuring that identical inputs always produce identical diagrams. According to the tt-a1i/archify source code, every operation—from validation to final render—is fully reproducible and machine-verified. ## What Archify Does: The Four-Stage Pipeline The core workflow in `archify/bin/archify.mjs` implements four deterministic stages that guarantee consistent, validated output: - **Generate**: An LLM or user creates a **typed JSON IR** describing components, relationships, and metadata. This structured intermediate representation serves as the single source of truth for the entire pipeline. - **Validate**: Bundled validators enforce schema correctness, layout rules, and routing constraints. When validation fails, the system emits machine-readable diagnostics through the `inputDiagnostic` format defined at lines 60-76 of `archify/bin/archify.mjs`, allowing automated error handling. - **Preview** (optional): A watch-mode desktop session monitors a single JSON file and reloads only after the candidate passes **all** validation gates. This preserves the last-good artifact during failures, as documented in the README at lines 176-182. - **Deliver**: The verified JSON renders to HTML/SVG (and optionally PNG or WebM), atomically replacing the previous artifact. The CLI can automatically open the result using the `--open` flag. Because each stage is fully deterministic, the resulting diagrams are **shareable, version-controlled, and reproducible** across different environments and sessions. ## Installing Archify Archify distributes as an OpenAI-compatible skill installable via `npx`. The canonical installation command shown in the README (lines 30-34) works for all supported agents: ```bash npx skills add tt-a1i/archify -g ``` For non-interactive Cursor installations, use the expanded form from the README (lines 4-8): ```bash npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes ``` Archify functions without an existing repository; you can begin immediately from a plain text description. ## Creating Your First Diagram ### Describing Your System Start with a **short natural-language description** that the LLM translates into JSON IR. According to the README (lines 22-28), a minimal description looks like: ``` Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback. ``` For evidence-backed diagrams from existing codebases, prompt the agent to analyze the repository first: ``` Analyze this repository, then use archify to create a high-level runtime architecture diagram. Show 8–12 core components, one primary path, external dependencies, and trust boundaries. ``` ### Running the CLI The CLI implementation in `archify/bin/archify.mjs` (lines 15-33) exposes several commands. To render your first architecture diagram from a saved JSON file: ```bash archify render architecture description.json diagram.html --quality showcase ``` This command invokes the architecture renderer and outputs an interactive HTML file. The `--quality showcase` flag optimizes the output for presentation purposes. ## Core CLI Commands The usage text in `archify/bin/archify.mjs` defines six primary commands for different workflow stages: | Command | Purpose | |---------|---------| | `archify render [output.html]` | Generates diagrams from JSON IR. | | `archify validate ` | Checks JSON against schema and layout rules. | | `archify preview ` | Watches a file and auto-reloads only after validation passes. | | `archify deliver ` | One-shot render that atomically replaces the previous artifact. | | `archify compare architecture ` | Produces a delta view showing added/removed/changed facts. | | `archify guide ""` | Displays pre-written scenario descriptions for ad-hoc prompts. | ### Validating Input Before rendering, verify your JSON IR meets all schema requirements: ```bash archify validate workflow examples/agent-tool-call.workflow.json --json ``` The `--json` flag outputs machine-readable diagnostics compatible with the `inputDiagnostic` structure defined in the CLI source. This enables CI/CD pipelines to programmatically handle validation failures. ### Preview and Deliver Workflows For iterative development, use the preview command to maintain a live-updating view: ```bash archify preview sequence seq.json ``` For final artifacts, the deliver command ensures atomic replacement: ```bash archify deliver architecture final.json --open ``` The `--open` flag automatically launches the generated HTML in your default browser. ## Interacting with the Viewer The generated HTML includes an interactive viewer powered by JavaScript modules in the `viewer/` directory (such as [`viewer/semantic-radar.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-radar.js)). The README (lines 38-52 and 80-88) documents the following controls: - **Search nodes**: Press `/` to filter components by name. - **Focus**: Press `F` to isolate specific elements. - **Trace reach**: Use `Upstream` or `Downstream` to highlight dependency chains. - **Probe routes**: Press `R` to analyze paths through the system. - **Compare roles**: Press `L` to activate lens comparison mode. - **Open radar**: Press `M` to view the semantic radar overlay. - **Switch styles**: Press `S` to cycle through visual themes. The **Export** menu provides static asset generation in PNG, SVG, and WebM formats for documentation and presentation purposes. ## Summary - **Archify** transforms JSON IR into interactive system diagrams through deterministic Generate, Validate, Preview, and Deliver stages. - Install via `npx skills add tt-a1i/archify -g` for immediate use with compatible AI agents. - The CLI in `archify/bin/archify.mjs` provides `render`, `validate`, `preview`, `deliver`, and `compare` commands for complete workflow control. - Validation produces machine-readable `inputDiagnostic` JSON for automated error handling. - The interactive viewer supports keyboard shortcuts for search, focus, route probing, and multi-format export. ## Frequently Asked Questions ### How do I validate my JSON IR before rendering? Use the `archify validate` command with the `--json` flag to receive machine-readable diagnostics. For example: `archify validate architecture myfile.json --json`. This checks against the schema definitions in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) and returns structured error data via the `inputDiagnostic` format if constraints are violated. ### Can Archify work without an existing code repository? Yes. Archify functions entirely from natural language descriptions or hand-crafted JSON IR. You can start with a simple text description like "Browser -> API -> Database" and let the LLM generate the structured intermediate representation, or write the JSON manually following the schema specifications. ### What makes Archify outputs reproducible? The four-stage pipeline enforces determinism at every step: the JSON IR serves as an immutable input specification, validators ensure structural consistency before rendering, and the renderers produce identical visual output for identical input. This makes diagrams suitable for version control and ensures team members see the same architecture when sharing JSON files. ### How do I generate a diff between two architecture versions? Use the `archify compare` command: `archify compare architecture base.json head.json delta.html`. This produces an interactive delta view highlighting added, removed, or changed components and relationships between the two snapshots, useful for reviewing architectural evolution in pull requests.