Core Features of Archify: Interactive System Mapping with Deterministic Validation

Archify is a Node.js-based rendering and validation engine that transforms codebase descriptions into deterministic, interactive system diagrams packaged as single-file HTML artifacts with full provenance tracking.

The tt-a1i/archify repository provides a deterministic workflow for generating architectural diagrams directly from chat or CLI without requiring separate UI editors or repositories. The system combines typed JSON intermediate representations with atomic validation to ensure every rendered artifact is grounded in verifiable source evidence rather than hallucinated topology.

Multi-Format Diagram Generation with Typed JSON IR

Archify supports five distinct diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each with four visual presets and dark/light themes. Every diagram type is backed by a strict JSON schema defined in archify/schemas/README.md, which the CLI validates before any rendering occurs.

The generate command accepts plain-text descriptions via stdin and outputs a typed JSON intermediate representation (IR). This IR serves as the single source of truth for all downstream operations, ensuring consistency across the build pipeline.

# Generate a diagram IR from a plain-text description

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

Atomic Validation and Change Review

The validate command performs schema validation, layout verification, routing checks, and label validation against the JSON IR. When validation fails, Archify returns machine-readable repair receipts via the --json flag, enabling automated remediation workflows.

For architecture reviews, Archify compares two validated snapshots as Before / Delta / After views. This comparison surfaces exact facts about added, removed, changed, moved, and rerouted components without claiming runtime impact or inventing dependencies.

# Validate the generated IR with detailed error reporting

node archify/bin/archify.mjs validate architecture output.json --json

Grounded Interaction and Source Provenance

Unlike systems that hallucinate topology, Archify enables grounded interaction through revision-verified source tracing. Users can search nodes, trace upstream and downstream reach, compare semantic roles, and open exact source files using SRC n markers that specify line ranges and revisions.

This provenance system ensures that every node in the diagram maps to an actual code artifact, preventing the invention of runtime relationships or non-existent dependencies.

Deterministic Build Pipeline and Live Preview

The preview command implements a Last-Good Live Preview pattern. A desktop loop watches the source JSON file and refreshes the diagram only after the candidate passes all validation checks. If a save produces an invalid state, the previous verified diagram remains visible, preventing broken artifacts from entering the workflow.

The deliver command atomically replaces the previous file only upon successful validation, outputting a self-contained HTML file bundled with PNG, SVG, WebM, and 1200×630 share-card images for social distribution. This single-file output is fully portable and retains complete viewer functionality without external dependencies.

# Start the last-good live preview server

node archify/bin/archify.mjs preview architecture output.json preview.html

# Deliver the final artifact with share cards and open in browser

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

Universal Agent Installation

Archify ships as a single-file skill installable across multiple AI coding agents and platforms. The npx skills add command enables installation for Cursor, Claude Code, Codex CLI, Opencode, Raven, and DeepSeek Harness without repository cloning or complex configuration.

# One-line install for any supported agent

npx skills add tt-a1i/archify -g

The archify/SKILL.md file contains the complete contract describing capabilities, inputs, and outputs for agent integration, while archify/examples/web-app.html demonstrates a live interactive diagram viewer.

Summary

• Typed JSON IR: Every diagram type uses a strict schema defined in archify/schemas/README.md, ensuring type safety from generation to delivery.
• Atomic Validation: The validate command checks schema, layout, and routing, returning machine-readable repair receipts on failure.
• Grounded Provenance: SRC n markers link diagram nodes to exact revision-verified source files and line ranges.
• Last-Good Preview: The preview command only updates the visual output after successful validation, maintaining the previous good state during editing.
• Single-File Output: The deliver command produces a portable HTML file with embedded PNG, SVG, and WebM assets, plus social share cards.
• Universal Installation: Single-command installation via npx skills add supports Cursor, Claude Code, and other major AI agents.

Frequently Asked Questions

How does Archify validate diagram integrity before rendering?

Archify runs atomic validation through the archify/bin/archify.mjs validate command, which checks the JSON IR against the schema in archify/schemas/README.md. The validator inspects layout constraints, routing logic, and label formats. If validation fails, the system returns a machine-readable repair receipt via the --json flag, specific enough for automated fixes, and prevents the broken diagram from reaching the deliver stage.

Can Archify integrate with existing AI coding agents like Cursor or Claude Code?

Yes. Archify is distributed as a single-file skill that installs via npx skills add tt-a1i/archify -g. The repository supports Cursor, Claude Code, Codex CLI, Opencode, Raven, and DeepSeek Harvest through a unified installation mechanism documented in archify/SKILL.md, requiring no additional repository cloning or environment configuration.

What makes Archify's output "portable" compared to other diagramming tools?

The deliver command generates a single HTML file containing the complete diagram, viewer logic, and all assets including PNG, SVG, and WebM renders. Unlike tools that rely on temporary viewer states or external hosting, Archify's output is self-contained and deterministic, allowing the file to be opened directly in any browser or shared via static hosting without losing interactivity or visual fidelity.

How does the "Last-Good Live Preview" feature handle validation failures?

When running archify/bin/archify.mjs preview, the system watches the source JSON file for changes and attempts to validate the new content. If the candidate fails validation—due to schema errors or layout conflicts—the preview window retains the previous successfully validated diagram rather than displaying a broken state. This ensures developers always see a functional reference while iterating on complex system descriptions.

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