How to Generate Architectural Diagrams with Archify: A Complete Guide

Yes, Archify can generate polished, interactive architectural diagrams directly from a codebase or textual system description, with full support for component-level views, service boundaries, storage layers, and trust zones.

Archify is an open-source CLI tool and chat-based skill designed to transform raw code into visual system documentation. The Architecture diagram mode produces deterministic, schema-validated diagrams that can be inspected, shared, and exported without external services.

Understanding Archify's Architecture Diagram Mode

Archify supports five distinct diagram modes. The Architecture mode is specifically built for runtime system visualization:

• Architecture | Components, services, storage, boundaries — designed for high-level runtime architecture diagrams

This mode appears in the diagram type selector documented in README.md at lines 136-144, where users choose the appropriate visualization for their needs.

The JSON IR Pipeline

Every architectural diagram flows through a typed intermediate representation (IR) pipeline:

1. Generate — Create a JSON description of the system (*.architecture.json)
2. Validate — Check against architecture.schema.json for structural correctness
3. Render — Emit a self-contained HTML viewer with optional PNG/SVG/WebM export

The schema at archify/schemas/architecture.schema.json enforces deterministic layout rules and validates all nodes, edges, and boundary metadata before rendering occurs.

Generating Architecture Diagrams from the Command Line

Basic Repository Analysis

The fastest way to generate an architecture diagram is through the CLI entry point at archify/bin/archify.mjs:

# Install the skill globally (one-time setup)

npx skills add tt-a1i/archify -g

# Generate architecture diagram from current repository

node archify/bin/archify.mjs generate architecture . archify-output.html

This command produces two artifacts:

• archify-output.html — Interactive viewer with pan, zoom, and export controls
• archify-output.architecture.json — The typed source for regeneration or editing

Using the Guide Helper for Examples

Archify includes pre-built examples to demonstrate expected output structure:

# Display a sample web-app runtime architecture as JSON

node archify/bin/archify.mjs guide "Show a web-app runtime architecture" --json

Feed this output through the deliver command to render a complete HTML artifact:

node archify/bin/archify.mjs deliver --input sample.architecture.json --output demo.html

Agent-Driven Architecture Generation

Archify integrates with chat-based agents including Cursor, Raven, Claude Code, and native CLI. A typical agent interaction follows this pattern:

Use archify to map this repository's runtime architecture.
Show 8-12 core components, one primary path, external dependencies,
and trust boundaries.

The agent invokes Archify under the hood, returns a shareable HTML link, and supports iterative refinement: adding nodes, changing layouts, or exporting share cards.

Exporting and Sharing Architecture Diagrams

HTML Viewer Embedding

The rendered output is pure HTML with static assets — no external service required. Embed diagrams in:

• README files
• Release notes
• Documentation portals

Share Card Generation

Export presentation-ready PNGs (1200 × 630) optimized for social media:

# CLI export from validated JSON

node archify/bin/archify.mjs export --type=share-card archify-output.architecture.json

Or use the interactive viewer: press E → Copy Share Card to capture the current viewport.

Key Source Files for Architecture Diagrams

File	Purpose
archify/bin/archify.mjs	Main CLI — handles generate, validate, preview, deliver subcommands
archify/schemas/architecture.schema.json	JSON Schema defining valid Architecture diagram structure
archify/examples/web-app.architecture.json	Sample input demonstrating component/service/boundary representation
archify/examples/web-app.html	Rendered viewer output showing final interactive diagram
archify/SKILL.md	Agent integration contract describing renderer protocol

Architecture Diagram Schema Structure

The architecture.schema.json enforces a typed structure that includes:

• Nodes — Components, services, databases, external systems
• Edges — Data flow, dependencies, calls
• Boundaries — Trust zones, deployment groups, organizational ownership
• Metadata — Labels, descriptions, versioning for diagram evolution

This schema validation guarantees that diagrams generated across different environments remain structurally compatible and render predictably.

Summary

• Archify generates architectural diagrams through its dedicated Architecture mode, targeting components, services, storage, and trust boundaries
• The JSON IR pipeline (generate → validate → render) ensures deterministic, trustworthy output
• CLI and agent integrations support both automated and conversational workflows
• Self-contained HTML viewers enable local inspection and embedding without external dependencies
• Share card exports (PNG/SVG/WebM) provide publication-ready assets for documentation and social distribution

Frequently Asked Questions

What types of architectural diagrams can Archify create?

Archify produces runtime architecture diagrams showing component relationships, service boundaries, storage layers, and trust zones. The Architecture mode specifically targets high-level system views rather than code-level structures like class hierarchies or sequence flows.

How does Archify ensure diagram quality and consistency?

All architecture diagrams pass through schema validation against architecture.schema.json before rendering. This typed IR approach eliminates malformed output and guarantees that node relationships, edge directions, and boundary definitions follow predictable structural rules.

Can I edit an architecture diagram after generation?

Yes. Archify emits the source JSON (*.architecture.json) alongside the HTML viewer. Modify this JSON directly or through iterative agent prompts, then re-run archify.mjs deliver to regenerate the visual output with changes applied.

Is Archify suitable for CI/CD pipeline integration?

Yes. The CLI interface at archify/bin/archify.mjs supports non-interactive execution with exit codes for validation failures. Generate architecture diagrams as build artifacts, gate releases on schema validation, or publish share cards automatically alongside documentation deployments.

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