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

> Discover tt-a1i/archify, an AI agent skill that generates deterministic architecture diagrams from natural language or JSON. Understand your system architecture with interactive HTML diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: getting-started
- Published: 2026-09-12

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
npx skills add tt-a1i/archify -g

```

### Generating Diagrams from Descriptions

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

```bash

# 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:

```bash
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:

```text
> 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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) – Skill contract defining command surface and metadata schema
- [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.