What Is tt-a1i/archify? The AI Agent Skill for Deterministic Architecture Diagrams

tt-a1i/archify is a Node.js-based rendering, validation, and export engine that transforms natural-language or typed JSON system descriptions into deterministic, interactive HTML diagrams designed for AI agents including Cursor, Claude Code, Codex CLI, and OpenCode.

tt-a1i/archify functions as an installable agent skill that compiles strictly-typed JSON intermediate representations into self-contained visual artifacts. The repository provides a zero-dependency CLI and a portable viewer that enables interactive exploration of architecture, workflow, sequence, and data-flow diagrams without requiring external runtime dependencies.

Core Capabilities of tt-a1i/archify

Typed JSON IR and Schema Validation

The engine accepts a strictly-typed JSON intermediate representation (IR) that describes components, relationships, and layout metadata. Before rendering, the IR undergoes validation against JSON-Schema definitions stored in archify/schemas/README.md. Any validation failures generate a machine-readable repair receipt that agents can use for automatic correction.

Deterministic Compilation Pipeline

As implemented in tt-a1i/archify, the compilation process consists of pure functions that guarantee identical outputs for identical inputs. The render pipeline executes validation, layout, and export steps in a fixed order: if any step fails, the build aborts and returns diagnostic metadata. This determinism ensures reproducible diagrams across different environments and agent sessions.

Interactive Viewer and Exploration

The compiled output loads in a unified viewer defined in viewer/template.source.html, which implements keyboard shortcuts (/ for search, R for route probe, L for lens, M for focus mode) to query diagram metadata client-side. Users can export share-cards (1200×630 PNG images) for documentation or copy static assets to the clipboard directly from the browser interface.

Source-Evidence Linking

Nodes within the JSON IR can carry a SRC tag referencing specific lines in public repository commits. When activated in the viewer, these tags open the exact file and line range in the source repository, providing traceability from visual elements back to implementation code.

Architectural Layers

The tt-a1i/archify codebase organizes functionality into five distinct layers:

1. Skill Contract (archify/SKILL.md) – Defines the JSON schema, accepted commands, and metadata fields including meta.locale and visual_preset.

2. Schema Package (archify/schemas/) – Contains JSON-Schema definitions for each diagram type (Architecture, Workflow, Sequence, Data-Flow, Lifecycle), enforced by the validate command.

3. Renderers (archify/renderers/…) – Pure function modules that transform validated IR into SVG/HTML elements; for example, archify/renderers/architecture/render-architecture.mjs handles Architecture diagram generation.

4. Viewer (viewer/) – A lightweight web application that loads compiled HTML, registers interactive shortcuts, and implements helpers like radar views and semantic lenses.

5. CLI Utilities (scripts/ and archify/bin/) – Bootstrap scripts and the main entry point at archify/bin/archify.mjs exposing commands such as validate, preview, deliver, guide, and compare.

CLI Usage Examples

Installing the Skill Globally

Install tt-a1i/archify into the global skill directory for any supported agent:

npx skills add tt-a1i/archify -g

Generating Diagrams from Descriptions

Generate typed JSON IR from a natural language description and preview the result:

# Generate IR

node archify/bin/archify.mjs guide "Browser -> API -> Redis cache -> PostgreSQL fallback" --json

# Preview as HTML

node archify/bin/archify.mjs preview architecture \
  archify/examples/web-app.json \
  /tmp/web-app.html --quality showcase

Validating Existing Artifacts

Validate a workflow diagram against its schema and output a JSON receipt:

node archify/bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase --json

Exporting Share Cards from the Viewer

Once a diagram is open in the browser:

1. Press E to open the export menu.
2. Select Copy Share Card.
3. The 1200×630 PNG copies to the clipboard for pasting into documentation.

Using Inside Cursor

Invoke the skill directly within Cursor's agent interface:

> Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL.

Cursor will invoke the skill, request refinements if needed, and return the final HTML artifact.

Key Source Files

Understanding tt-a1i/archify requires familiarity with these critical paths:

• archify/SKILL.md – Skill contract defining command surface and metadata schema
• archify/schemas/README.md – JSON-Schema definitions for diagram validation
• archify/renderers/architecture/render-architecture.mjs – Core renderer producing SVG/HTML output
• viewer/template.source.html – Unified viewer UI with interactive controls
• archify/bin/archify.mjs – CLI entry point implementing guide, validate, preview, deliver, and compare commands
• archify/test/ – Jest-style test suite verifying deterministic layout and geometry

Summary

• tt-a1i/archify is a deterministic diagram engine packaged as an AI agent skill for Node.js environments
• It consumes typed JSON IR and compiles self-contained HTML files with interactive exploration features
• The architecture separates concerns into schema validation, pure-function renderers, and a lightweight browser viewer
• Source code traceability is built-in via SRC tags linking visual nodes to repository commits
• Zero external dependencies allow portable deployment via archify.zip or global skill installation

Frequently Asked Questions

What AI agents support tt-a1i/archify?

The skill is explicitly designed for Cursor, Claude Code, Codex CLI, and OpenCode. It installs via npx skills add and integrates with these agents' tool-calling interfaces to generate diagrams from natural language prompts.

How does deterministic compilation benefit architecture diagrams?

Deterministic compilation ensures that the same JSON IR input always produces identical HTML, SVG, or PNG outputs. This reproducibility is critical for version-controlled documentation and automated CI/CD pipelines where visual consistency across environments is mandatory.

What diagram types can tt-a1i/archify generate?

The engine supports Architecture, Workflow, Sequence, Data-Flow, and Lifecycle diagrams. Each type offers four visual presets and dark/light themes, with dedicated renderers located in archify/renderers/.

Can I use tt-a1i/archify without installing npm packages?

Yes. The repository ships archify.zip as a pre-packed skill bundle containing all necessary code. You can unzip this file into any skill directory and run node archify/bin/archify.mjs directly without downloading external dependencies.

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