# How to Use Archify for Architecture Diagrams: A Step-by-Step Guide

> Learn to create stunning architecture diagrams with Archify. This guide shows you how to convert plain English descriptions into interactive diagrams using the tt-a1i/archify repository. Get started today.

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

---

**Archify converts plain-English system descriptions into polished, interactive architecture diagrams through a JSON-based intermediate representation and self-contained HTML output.**

This guide walks through installing and using Archify to create professional architecture diagrams. The tool lives in the `tt-a1i/archify` repository and supports multiple diagram types, but its **Architecture** mode excels at visualizing system components, trust boundaries, and deployment relationships.

## Installation and Setup

Archify installs as a global skill that integrates with your CLI or agent environment.

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

```

This command, documented in [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 30-33), registers the skill so you can invoke it from any directory.

## Selecting the Architecture Diagram Type

Archify supports five diagram modes. For system architecture visualization, choose **Architecture**:

| Diagram Type | Best For |
|-------------|----------|
| Architecture | System components, boundaries, deployment topology |
| Workflow | Business processes, decision flows |
| Sequence | Inter-service call chains over time |
| Data Flow | Information pipelines, ETL patterns |
| Lifecycle | State transitions, release stages |

The Architecture mode specifically handles core components, primary paths, external dependencies, and trust boundaries—as defined in the diagram-type table at [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) lines 38-45.

## Writing Effective Architecture Prompts

A well-bounded prompt produces cleaner diagrams. Describe:

- **Audience need** — who will read this diagram
- **Scope boundaries** — core components, primary path, external systems
- **Optional profile** — `deployment-ownership` for PR reviews or production comparisons

Example prompt structure from [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 17-32):

```

Analyze this repository, then use Archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

```

## Generating Diagrams with the CLI

The CLI entry point at `archify/bin/archify.mjs` handles the full pipeline: prompt parsing → JSON IR generation → schema validation → HTML rendering.

### Basic Architecture Generation

```bash
node archify/bin/archify.mjs \
  guide "Show a web app with API, JWT auth, Redis cache miss, PostgreSQL fallback" \
  --type architecture \
  --output web-app.html

```

This creates a self-contained HTML artifact with interactive components.

### Web Interface Alternative

For browser-based generation, open the start page:

```

.../start.html?type=architecture

```

Both methods produce the same typed JSON IR validated against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json).

## Iterative Refinement

Archify preserves the JSON source for precise updates. Modify diagrams through follow-up prompts:

```bash
node archify/bin/archify.mjs \
  guide "Add Kafka message bus, highlight the API→DB path" \
  --json examples/web-app.architecture.json \
  --output web-app-updated.html

```

The skill maintains context, allowing incremental changes like "add Redis" or "highlight the rollback path" without regenerating from scratch (see [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) lines 32-35).

## Architecture Delta for Reviews

Enable **deployment-ownership** profile for production-grade comparisons:

- **Before / Delta / After** views with machine-readable receipts
- Verified diffs for PR review or deployment planning
- Compliance tracking through structured output

Run comparisons with:

```bash
node archify/bin/archify.mjs compare architecture ...

```

This feature, described at [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) lines 46-53, generates auditable documentation for infrastructure changes.

## Export and Sharing Options

The HTML artifact includes an Export menu supporting:

- **PNG** — raster images for documents
- **SVG** — scalable vectors for presentations
- **Share cards** — 1200×630 optimized images for social platforms

The output remains a single HTML file embeddable anywhere, documented at [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) lines 79-88.

## Key Source Files Reference

| File | Purpose |
|------|---------|
| `archify/bin/archify.mjs` | CLI entry, orchestrates generation pipeline |
| [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) | Sample Architecture JSON source |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Typed schema for component/boundary model |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Agent skill contract (capabilities, I/O spec) |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Complete usage documentation |

## Summary

- **Install** Archify globally with `npx skills add tt-a1i/archify -g`
- **Select Architecture mode** for system component visualization
- **Write bounded prompts** specifying scope, audience, and profile
- **Generate** via CLI (`archify.mjs`) or web interface ([`start.html`](https://github.com/tt-a1i/archify/blob/main/start.html))
- **Iterate** using preserved JSON source for incremental refinements
- **Enable Delta mode** for production reviews with machine receipts
- **Export** to PNG, SVG, or share cards from the HTML artifact

## Frequently Asked Questions

### What input format does Archify use for architecture diagrams?

Archify uses a typed JSON intermediate representation defined by [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). You typically write natural language prompts; the CLI converts these to structured JSON containing components, boundaries, and optional deployment-ownership profiles.

### Can I edit an existing architecture diagram without starting over?

Yes. Pass the existing JSON file with the `--json` flag to `archify/bin/archify.mjs`. The skill preserves the source format, enabling precise edits like adding components or changing path highlighting through follow-up prompts.

### What is the deployment-ownership profile used for?

The deployment-ownership profile, defined in the architecture schema, enables Architecture Delta mode for PR reviews and production deployments. It generates verified Before/Delta/After comparisons with machine-readable receipts for compliance tracking.

### Where can I find example architecture diagrams?

The repository includes [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json), a complete sample demonstrating component structure, boundary definitions, and the optional deployment profile. Reference this file when crafting your own architecture specifications.