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

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.

npx skills add tt-a1i/archify -g

This command, documented in 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 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 (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

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.

Iterative Refinement

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

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

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

This feature, described at 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 lines 79-88.

Key Source Files Reference

File	Purpose
archify/bin/archify.mjs	CLI entry, orchestrates generation pipeline
archify/examples/web-app.architecture.json	Sample Architecture JSON source
archify/schemas/architecture.schema.json	Typed schema for component/boundary model
archify/SKILL.md	Agent skill contract (capabilities, I/O spec)
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)
• 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. 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, a complete sample demonstrating component structure, boundary definitions, and the optional deployment profile. Reference this file when crafting your own architecture specifications.

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