# How to Create an Architecture Diagram with Archify: A Complete Guide > Learn to create architecture diagrams effortlessly with Archify, a powerful CLI tool. Convert natural language to interactive diagrams using an LLM workflow. Get your guide now. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-09-06 --- **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`](https://github.com/tt-a1i/archify/blob/main/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. ```bash # 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: ```text 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: ```bash # 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html), confirms the generation source: ```html ``` ## Working with Architecture JSON Directly The generated JSON follows a structured schema you can manipulate. Examine [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) in the repository to understand the format: ```bash # 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: ```bash #!/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) as its base. For deeper customization, examine `archify/renderers/architecture/render-architecture.mjs` where the JSON-to-DOM transformation occurs.