What Is Archify and Which Problem Does It Solve?

Archify is a Node.js rendering and validation tool that transforms codebases or textual system descriptions into deterministic, interactive architecture diagrams, eliminating the gap between informal documentation and trustworthy visual representations.

Archify, hosted at tt-a1i/archify, provides a reproducible workflow for turning technical intent into communication-ready architecture maps. Unlike traditional diagramming tools that require manual drawing or produce untrustworthy auto-layouts, Archify compiles schema-validated JSON into verified HTML/SVG artifacts that accurately reflect system structure.

The Core Problem: Bridging Narrative and Visual Documentation

Software teams face a persistent documentation challenge: architectural knowledge lives in informal narrative explanations, code comments, or tribal knowledge, while visual documentation requires manual maintenance that quickly drifts out of sync. Traditional approaches fall into two unreliable categories.

Manual Diagramming Risks

Manual drawing tools create aesthetic inconsistency and version drift. When developers draw diagrams by hand, the visuals often reflect individual interpretation rather than system reality, and every code change requires manual updates that are frequently skipped.

Untrustworthy Auto-Generation

Generic auto-layout tools generate graphics that cannot be trusted to reflect exact architecture. These tools invent topology—placing components in spatial relationships that imply connections or hierarchies that do not exist in the code, creating misleading documentation.

How Archify Solves the Visualization Problem

According to the tt-a1i/archify source code, Archify addresses these issues through a four-pillar approach that prioritizes trust, determinism, and automation.

Typed JSON Intermediate Representation

Agents and developers produce a schema-validated JSON description of the system. In archify/schemas/README.md, the formal JSON schema ensures that every node, edge, and property is type-checked before rendering. This Intermediate Representation (IR) serves as the single source of truth, eliminating ambiguity between the system description and its visual form.

Deterministic Compilation

The archify/bin/archify.mjs CLI compiles JSON IR into HTML/SVG with deterministic layout algorithms. This guarantees that the same source always yields identical visual output, preventing the "works on my machine" problem for documentation. The compilation process respects explicit spatial relationships rather than inventing them.

Atomic Validation and Delivery

Every rendering passes a three-stage validation gate: schema validation, layout verification, and route checking. Only after passing all checks does the artifact replace the previous version. This atomic delivery mechanism ensures that broken or invalid diagrams never reach production documentation, maintaining documentation integrity.

Interactive, Searchable Output

The generated HTML—demonstrated in examples/web-app.html—creates interactive architecture maps without invented topology. Users can search nodes, trace upstream and downstream relationships, compare semantic roles, and play guided stories through the system, all grounded in the validated JSON source.

Generating Architecture Diagrams from Text

Archify operates as a command-line tool that accepts JSON IR and produces browser-ready HTML. The workflow begins with installing the skill and creating a system description.

Install the Archify skill globally using npx:

npx skills add tt-a1i/archify -g

Create a JSON source file describing your architecture. This example defines a web application stack with four nodes and their connections:

{
  "type": "architecture",
  "nodes": [
    {"id":"browser","label":"Browser"},
    {"id":"api","label":"API Server"},
    {"id":"redis","label":"Redis Cache"},
    {"id":"db","label":"PostgreSQL"}
  ],
  "edges": [
    {"source":"browser","target":"api"},
    {"source":"api","target":"redis"},
    {"source":"redis","target":"db"}
  ]
}

Validate and render the diagram using the deliver command implemented in archify/bin/archify.mjs:

node archify/bin/archify.mjs deliver architecture arch.json output.html --open --json

The deliver subcommand performs atomic validation before writing output.html, ensuring only verified diagrams are published. The --open flag launches the interactive viewer automatically.

Comparing Architecture Versions with Delta Visualization

Archify includes an Architecture Delta feature for tracking system evolution. The compare command analyzes two JSON IR files and generates a visual diff highlighting additions, removals, and modifications.

Run the comparison between a baseline and current version:

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

This produces delta.html with color-coded differences, enabling code reviewers to verify architectural changes visually before merging.

Live Preview During Development

For iterative development, the preview command provides hot-reload functionality that validates and refreshes the diagram on every file change.

Start the preview server:

node archify/bin/archify.mjs preview architecture arch.json /tmp/arch.html

As you edit arch.json, the CLI automatically revalidates the JSON schema and updates the preview only after successful validation. This prevents invalid states from corrupting your working diagram.

Key Implementation Files in the tt-a1i/archify Repository

Understanding Archify's architecture requires examining these critical source files:

• archify/bin/archify.mjs – The CLI entry point implementing validate, preview, deliver, and compare subcommands. This Node.js module handles argument parsing, schema validation, and artifact generation.

• archify/SKILL.md – Formal skill definition for AI agents (Cursor, Claude Code, Codex CLI, OpenCode). This file specifies how agents should generate valid JSON IR when describing systems.

• archify/schemas/README.md – Complete JSON schema reference documenting the typed IR structure, including node types, edge properties, and validation rules.

• examples/web-app.html – Production-ready viewer demonstration showing interactive features including search, relationship tracing, and guided tours.

• README.md – Project overview containing design rationale, quick-start instructions, and architectural philosophy.

Summary

• Archify is a Node.js CLI tool that compiles JSON system descriptions into deterministic, interactive HTML architecture diagrams hosted at tt-a1i/archify.
• It solves the documentation-to-diagram gap by replacing manual drawing and unreliable auto-layout with schema-validated, deterministic rendering.
• The four-pillar workflow—Typed JSON IR, Deterministic Compilation, Atomic Validation, and Interactive Output—ensures trustworthy, reproducible documentation.
• Key commands include deliver for publishing, compare for version diffing, and preview for development feedback.
• Source files like archify/bin/archify.mjs and archify/schemas/README.md implement the validation and compilation pipeline that guarantees diagram accuracy.

Frequently Asked Questions

What is Archify used for?

Archify transforms textual system descriptions or codebase analyses into interactive, shareable architecture diagrams. It serves development teams who need reliable visual documentation that stays synchronized with code changes without manual drawing maintenance.

How does Archify ensure diagram accuracy?

Archify implements atomic validation where every diagram passes schema checks (defined in archify/schemas/README.md), layout verification, and route validation before publication. The deterministic compilation in archify/bin/archify.mjs ensures that identical JSON IR always produces identical visual output, eliminating layout drift.

Can Archify integrate with AI coding agents?

Yes. The archify/SKILL.md file defines a formal skill specification for agents like Cursor, Claude Code, Codex CLI, and OpenCode. These agents can generate schema-validated JSON IR automatically from codebase analysis, creating architecture diagrams directly from code without human drawing intervention.

What output formats does Archify support?

Archify compiles JSON IR into HTML/SVG artifacts. The HTML output includes interactive JavaScript for searching nodes, tracing upstream and downstream relationships, and viewing semantic comparisons, as demonstrated in examples/web-app.html.

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