# How to Generate Architectural Diagrams with Archify: A Complete Guide

> Learn how to generate architectural diagrams with Archify. This guide shows you how to create interactive diagrams from your codebase or system descriptions for clear visualization.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/archify-output.html) — Interactive viewer with pan, zoom, and export controls
- [`archify-output.architecture.json`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

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

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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | JSON Schema defining valid Architecture diagram structure |
| [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) | Sample input demonstrating component/service/boundary representation |
| [`archify/examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.html) | Rendered viewer output showing final interactive diagram |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Agent integration contract describing renderer protocol |

## Architecture Diagram Schema Structure

The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.