Archify Usage Examples: How to Generate Interactive System Maps from Code

Archify transforms natural language prompts or repository snapshots into self-contained, interactive HTML system maps through a three-stage pipeline of generation, validation, and delivery.

These Archify usage examples demonstrate how the tt-a1i/archify agent skill converts architectural descriptions into browser-ready visualizations. Whether you are documenting a web application or comparing infrastructure changes, Archify produces semantic topology diagrams that reflect actual spatial relationships rather than generic grid layouts.

Understanding the Archify Workflow

Every Archify operation follows three tightly-coupled stages implemented in the core source code.

Generation

Claude (or another LLM) receives your prompt, infers spatial relationships between architectural components, and emits a typed JSON Intermediate Representation (IR). This IR conforms to one of Archify’s five schemata: architecture, workflow, sequence, data-flow, or lifecycle.

Validation

The generated JSON is checked against corresponding JSON Schemas and deterministic layout rules defined in the validator. These rules enforce constraints like node-overlap prevention and lane-crossing detection. Errors are returned in a machine-readable format so the LLM can self-correct before rendering.

Delivery

A type-specific renderer consumes the verified IR and produces a single, self-contained HTML artifact. According to the source in archify/bin/archify.mjs, this artifact includes theme toggles, visual presets, and export options for PNG, SVG, WebM, and 1200×630 share cards.

Installation and Global Setup

Install Archify as a global skill to make it available across your agent sessions.

npx skills add tt-a1i/archify -g

This command registers the skill globally, allowing you to invoke Archify commands from any directory without local installation.

Core Usage Examples

Rendering a Diagram from JSON

To convert an existing JSON scenario into an interactive HTML file, use the render command defined in archify/bin/archify.mjs:

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

This command loads the JSON IR, validates it against the architecture schema, and outputs web-app.html with full interactive controls. The examples/web-app.html file in the repository demonstrates the resulting output with all visual presets and theme toggles enabled.

Creating Runtime Diagrams from Repositories

For agent-driven workflows, you can generate maps directly from repository analysis:

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

The agent will generate the IR internally, run archify deliver, and return an HTML file. This file can be opened locally in any browser or shared via the automatically generated share-card. This workflow leverages the generation stage documented in docs/article-archify.md to produce semantic layouts where components like Identity Providers are positioned outside AWS regions based on their actual relationships rather than arbitrary grid placement.

Comparing Architecture Snapshots (Delta View)

Track infrastructure changes over time using the delta comparison feature implemented in archify/delta/architecture-delta.mjs:

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

This command produces a delta visualization highlighting changes between two architectural states. The output includes a receipt with SHA-256 hashes for provenance tracking, ensuring you can verify the integrity of compared snapshots.

Using the Scenario Guide

Explore built-in scenarios through the interactive guide script located at archify/recipes/scenarios.mjs:

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

The guide maps human-readable prompts to concrete JSON IR instances for all five diagram types. You can pipe the output directly to the render command to visualize specific architectural patterns without writing custom JSON.

Exploring the Generated Output

Archify diagrams are engineered for semantic topology rather than automatic grid layouts. Because the LLM performs layout judgment during generation, elements appear in spatially meaningful positions—for example, external authentication services render outside cloud provider boundaries.

Each generated HTML file includes:

• Deep-linking capabilities for focused inspection of specific nodes, routes, or lenses
• Theme toggles switching between light and dark modes
• Export options for PNG, SVG, and WebM formats
• Share cards sized at 1200×630 pixels for social media distribution

Summary

• Archify uses a three-stage pipeline (generation, validation, delivery) to convert prompts into interactive HTML system maps.
• Install globally via npx skills add tt-a1i/archify -g to enable CLI access from any directory.
• Use archify/bin/archify.mjs render to convert JSON IR files into self-contained HTML artifacts.
• Generate diagrams directly from repository analysis by prompting your agent to map runtime architecture.
• Compare architectural versions using archify compare, which outputs delta visualizations with SHA-256 provenance.
• Reference archify/recipes/scenarios.mjs for pre-built scenario templates covering all five supported diagram schemata.

Frequently Asked Questions

How does Archify differ from traditional diagramming tools?

Traditional tools rely on auto-layout engines that position nodes in uniform grids. Archify delegates layout decisions to the LLM during the generation stage, producing semantic topology where spatial relationships reflect actual architectural constraints. As documented in docs/article-archify.md, experiments proved that pure CSS changes cannot compensate for missing spatial reasoning.

What file formats does Archify support for input and output?

Archify accepts JSON Intermediate Representation files conforming to one of five schemata (architecture, workflow, sequence, data-flow, lifecycle). Output is always a self-contained HTML file that requires no external dependencies. The HTML includes embedded JavaScript for interactivity and can export to PNG, SVG, or WebM formats directly from the browser.

Where is the CLI entry point located in the repository?

The primary CLI logic resides in archify/bin/archify.mjs. This file handles command parsing, environment setup, and orchestration of the validator, renderers, and delivery modules. All user-facing commands including render, compare, and guide route through this entry point.

Can Archify generate diagrams without manual JSON authoring?

Yes. Instead of writing JSON manually, use the scenario guide via archify guide or prompt your agent to analyze a repository directly. These methods leverage the LLM to generate the JSON IR automatically, allowing you to create complex architectural visualizations from natural language descriptions alone.

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