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

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.

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, 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.

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:

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. 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.

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.

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 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, 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, 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 provides the complete design narrative with experiment results.

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