# How to Use Archify: 5 Practical Examples from the Source Code

> Explore 5 practical Archify examples from its source code. Learn to render diagrams using CLI commands or natural language prompts with this powerful tool.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-13

---

**You can use Archify by installing it as a global skill with `npx skills add tt-a1i/archify -g`, then rendering diagrams via CLI commands like `archify render` or natural-language prompts to your agent.**

Archify is an **agent skill** that converts natural-language descriptions or repository snapshots into interactive, browser-rendered system architecture maps. According to the `tt-a1i/archify` source code, the tool implements a three-stage pipeline—generation, validation, and delivery—to produce self-contained HTML artifacts with semantic spatial reasoning rather than generic auto-layout.

## Installation and Global Setup

The fastest way to start using Archify is installing it as a global skill through the skills registry.

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

```

This registers the `archify` command globally, enabling CLI access to all rendering engines. The installation process is documented in the repository's [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md), which serves as the primary entry point for new users.

## Example 1: Render a JSON Architecture File

Once installed, you can render a pre-defined architecture scenario directly to HTML. The CLI entry point in `archify/bin/archify.mjs` handles command parsing, environment setup, and renderer invocation.

```bash
node archify/bin/archify.mjs render architecture examples/web-app.architecture.json web-app.html

```

This command:
- Loads the **architecture schema** validator
- Processes the JSON intermediate representation (IR)
- Outputs a **self-contained HTML file** with theme toggles and export options

The output includes visual presets, PNG/SVG/WebM export capabilities, and 1200×630 share cards for social distribution.

## Example 2: Generate Runtime Diagrams from Repository Analysis

Archify's core strength is **LLM-driven spatial reasoning**. Instead of manually authoring JSON, you can prompt your agent to analyze a codebase:

```text
Ask your agent:
  Use archify to map this repository's runtime architecture.

```

Behind the scenes, the agent:
1. Infers component relationships from source files
2. Generates typed JSON IR conforming to one of five schemata: **architecture**, **workflow**, **sequence**, **data-flow**, or **lifecycle**
3. Executes `archify deliver` to produce the final HTML artifact

This workflow is captured in the "Quick start" section of [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md). The LLM performs layout judgment—placing an Identity Provider *outside* an AWS region boundary, for example—rather than relying on a generic grid algorithm.

## Example 3: Compare Architecture Versions (Delta View)

Track architectural evolution using the built-in comparison engine. The delta runtime in `archify/delta/architecture-delta.mjs` generates visual diffs with cryptographic provenance.

```bash
archify compare architecture base.json head.json delta.html --json

```

The `--json` flag emits a machine-readable receipt containing **SHA-256 hashes** for both snapshots, enabling audit trails and CI/CD integration.

## Example 4: Explore Built-In Scenarios

The scenario guide system helps you learn valid IR patterns without writing JSON from scratch. The `archify/recipes/scenarios.mjs` module maps human-readable prompts to concrete scenario definitions.

```bash
archify guide "Show an API request with Redis cache miss"

```

This returns a complete JSON IR that you can immediately pipe to `archify render`. The recipe system covers common patterns across all five diagram types, making it an effective learning tool.

## Example 5: Inspect the Interactive Output

The generated HTML artifacts are fully self-contained. Open [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) in any modern browser to explore:

- **Theme toggles** (light/dark/high-contrast)
- **Visual presets** for different presentation contexts
- **Deep-linking** to specific nodes, routes, or lenses
- **Export options** for static and animated formats

Each output file embeds all dependencies, requiring no build step or external hosting.

## Core Architecture and Design Philosophy

Archify's pipeline consists of three tightly-coupled stages implemented across the source tree:

| Stage | Implementation | Purpose |
|-------|---------------|---------|
| **Generation** | LLM prompt engineering + typed JSON IR | Infers semantic topology from natural language |
| **Validation** | JSON Schema + deterministic layout rules | Ensures renderability and catches structural errors |
| **Delivery** | Type-specific renderers in `archify/bin/archify.mjs` | Produces final HTML with interactive controls |

The design philosophy emphasizes **semantic topology over geometric uniformity**. As documented in [`docs/article-archify.md`](https://github.com/tt-a1i/archify/blob/main/docs/article-archify.md), a blind-test experiment demonstrated that pure CSS adjustments cannot compensate for missing spatial-reasoning in the generation phase. The LLM must understand *why* components belong in specific regions, not merely *where* to place them.

## Summary

- **Install globally** with `npx skills add tt-a1i/archify -g` to enable CLI access
- **Render JSON directly** using `archify/bin/archify.mjs render` with schema-specific handlers
- **Use natural language** to trigger agent-driven analysis and automatic diagram generation
- **Compare versions** via `archify compare` with cryptographic provenance receipts
- **Learn from examples** through the `archify/recipes/scenarios.mjs` guide system
- **Export and share** interactive HTML with embedded theme controls and multiple format outputs

## Frequently Asked Questions

### What file formats does Archify output?

Archify produces **self-contained HTML files** as the primary output. These include embedded JavaScript for interactivity and support exporting to **PNG**, **SVG**, and **WebM** formats. Share cards at 1200×630 resolution are automatically generated for social distribution.

### Can I use Archify without writing JSON manually?

Yes. The **agent-driven workflow** allows you to describe your architecture in natural language. The LLM generates the typed JSON IR internally, validates it against the appropriate schema, and returns the final HTML artifact. This is the recommended path for most users.

### How does Archify handle diagram layout differently from other tools?

Unlike generic auto-layout engines, Archify performs **spatial reasoning during generation**. The LLM infers semantic relationships—such as trust boundaries, network zones, and ownership boundaries—and positions components accordingly. This produces diagrams where an Identity Provider appears *outside* an AWS region because it isn't an AWS resource, rather than being forced into a uniform grid.

### Where can I find example diagrams to study?

The repository includes [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html), a full-featured demonstration showing all visual presets and interactive controls. Additionally, `archify/recipes/scenarios.mjs` contains mappings from common prompts to working JSON IR, and [`docs/article-archify.md`](https://github.com/tt-a1i/archify/blob/main/docs/article-archify.md) provides the complete design narrative with experiment results.