How to Create an Architecture Diagram with Archify: A Complete Guide

Archify is a zero-dependency CLI tool that converts natural-language system descriptions into interactive, styled architecture diagrams using an LLM-driven workflow.

This guide walks you through creating professional architecture diagrams with Archify, an open-source tool developed by tt-a1i/archify. Unlike traditional diagramming tools that require manual dragging and connecting of boxes, Archify lets you describe what you want to visualize in plain English and handles the rest.

Understanding Archify's Architecture Diagram Workflow

Archify operates through a three-stage pipeline that transforms your scenario into a rendered visualization.

The Three Core Stages

1. Scenario input — You provide a natural-language description of the system or process
2. JSON generation — Archify uses a language model to generate structured architecture JSON
3. HTML rendering — The built-in renderer produces an interactive diagram using template.html

The entire workflow is orchestrated through the main entry point at archify/bin/archify.mjs, with recipe logic in archify/recipes/scenarios.mjs and rendering handled by archify/renderers/architecture/render-architecture.mjs.

Step 1: Describe Your Architecture Scenario

The quality of your diagram depends on the clarity of your initial prompt. Archify uses a "question-first" approach — you state what you want to understand about a system rather than prescribing diagram types upfront.

Effective prompts include:

• System components and their interactions ("User signs up, receives a welcome email, and is added to the CRM")
• Data flows and transformations
• Lifecycle stages of an entity
• Sequence of operations across services

The recipe system in archify/recipes/scenarios.mjs automatically selects appropriate diagram patterns based on your description's semantic structure.

Step 2: Generate Architecture JSON with archify guide

Run the guide command to process your scenario and generate the underlying architecture representation.

# Basic usage — generates diagram and opens in default viewer

archify guide "User signs up, receives a welcome email, and is added to the CRM"

# Export raw JSON for inspection or manual editing

archify guide "E-commerce checkout flow with inventory check and payment processing" --json > checkout.json

# Specify language for internationalized output

archify guide "Microservices deployment pipeline" --lang zh --json > pipeline.json

The --json flag is particularly useful when you want to:

• Version control your architecture definitions
• Modify generated structures before rendering
• Integrate with CI/CD pipelines

According to the source code in archify/bin/archify.mjs, the CLI signature supports:

archify guide [scenario or question] [--json] [--lang en|zh]

Step 3: Render to Interactive HTML

By default, Archify renders diagrams to a self-contained HTML file. You can also render previously generated JSON:

# Render a saved architecture JSON file

archify render signup.json

# Default output is archify.html in current directory

open archify.html

The renderer at archify/renderers/architecture/render-architecture.mjs processes the JSON and injects it into the template at scripts/guide-template.html. The resulting HTML includes:

• Guided views — Step-by-step walkthrough modes
• Semantic lenses — Filter by concern (security, performance, data flow)
• Motion cues — Animated transitions between states
• Export options — PNG, SVG, or printable formats

The template footer, defined in scripts/guide-template.html, confirms the generation source:

<footer>
  <div class="shell">
    <span data-i18n="footerLeft">Generated from the same recipe source as the Archify CLI.</span>
    <span>archify guide "your scenario"</span>
    <span data-i18n="versionLabel">Scenario guide / development / v[[ARCHIFY_VERSION]]</span>
  </div>
</footer>

Working with Architecture JSON Directly

The generated JSON follows a structured schema you can manipulate. Examine examples/archify-repo.architecture.json in the repository to understand the format:

# Fetch and study the example output

curl -s https://raw.githubusercontent.com/tt-a1i/archify/main/examples/archify-repo.architecture.json | jq .

This example illustrates the JSON schema including nodes, edges, metadata, and rendering hints that define the final diagram appearance.

Integration and Automation Patterns

Archify's zero-dependency design makes it ideal for automated workflows. Because it bundles its own dependencies and uses no external Node modules, you can:

• Run it in minimal CI containers without npm install
• Cache the single executable for reproducible builds
• Generate architecture documentation on every code change

A typical documentation pipeline:

#!/bin/bash

# .github/workflows/architecture-docs.yml excerpt

archify guide "Current system architecture based on $(git describe --tags)" --json > docs/architecture.json
archify render docs/architecture.json --output docs/architecture.html
git add docs/architecture.html docs/architecture.json

Summary

• Archify eliminates manual diagramming by converting natural language to structured visualizations
• Use archify guide "your scenario" to generate diagrams; add --json for programmable output
• The rendered HTML at archify.html provides rich interactivity without external dependencies
• Key implementation files: archify/bin/archify.mjs (CLI), archify/recipes/scenarios.mjs (prompt processing), and archify/renderers/architecture/render-architecture.mjs (visualization)
• Zero-dependency architecture enables CI/CD integration and portable documentation generation

Frequently Asked Questions

What makes Archify different from tools like Mermaid or PlantUML?

Archify uses LLM interpretation rather than domain-specific languages. Where Mermaid requires learning syntax like graph TD; A-->B, Archify accepts plain English descriptions. The recipe system in archify/recipes/scenarios.mjs handles diagram-type selection automatically based on semantic analysis of your prompt.

Can I edit a generated architecture diagram manually?

Yes, through the JSON intermediate format. Generate with --json, modify the structured output, then render with archify render. The schema in examples/archify-repo.architecture.json demonstrates available fields for nodes, edges, styling, and metadata.

Does Archify require an internet connection?

The guide command requires LLM API access for scenario interpretation, but rendering works offline. Once you have architecture JSON, archify render processes everything locally using the bundled template at scripts/guide-template.html without external calls.

How do I customize the visual styling of generated diagrams?

Modify the template or fork the renderer. The HTML output uses scripts/guide-template.html as its base. For deeper customization, examine archify/renderers/architecture/render-architecture.mjs where the JSON-to-DOM transformation occurs.

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