How Archify Generates Diagrams from Plain English: A Technical Deep Dive

Archify generates diagrams from plain English by sending user descriptions to a Claude-powered language model that outputs structured JSON, which is then validated against JSON schemas and rendered into SVG diagrams by specialized layout engines.

Archify is an open-source tool that transforms natural language system descriptions into professional architecture diagrams without manual drawing. The repository tt-a1i/archify implements a robust pipeline that bridges the gap between ambiguous human language and precise visual representations. Understanding how Archify generates diagrams from plain English reveals a sophisticated interplay of LLM prompt engineering, schema validation, and modular SVG rendering.

The Three-Stage Architecture Pipeline

Archify converts text to graphics through a strict three-stage pipeline that ensures type safety and visual consistency across all diagram types.

Stage 1: Natural Language to Structured JSON

The process begins when plain English text is sent to a Claude LLM skill. The model interprets system descriptions and outputs JSON conforming to Archify's strict architecture schema. These schema definitions reside in archify/schemas/*.schema.json, with the core architecture schema defining required fields like meta.title, lanes, and nodes. For example, a description of a web application with frontend and backend services produces JSON with nodes representing services and edges representing their connections.

Stage 2: Validation and Normalization

Raw LLM output requires rigorous validation before rendering. Archify validates generated JSON using validators created by archify/scripts/generate-validators.mjs. This script auto-generates runtime validators from the JSON schemas, ensuring required fields are present, identifiers are unique, and the structure matches the expected diagram type—whether workflow, sequence, dataflow, lifecycle, or architecture diagrams.

Stage 3: SVG Rendering and Layout Calculation

Once validated, the JSON data moves to diagram-specific renderers. For workflow diagrams, archify/renderers/workflow/render-workflow.mjs serves as the entry point, computing layout dimensions, positioning nodes and edges, and injecting them into HTML/SVG templates. Each diagram type maintains its own renderer module for specialized layout logic, calculating exact coordinates for nodes and routing paths for connecting edges.

End-to-End Workflow Example

Consider a user describing: "A web app consists of a front-end service that talks to an API gateway, which routes requests to an authentication service and a product-catalog microservice."

1. CLI Invocation: The user runs archify render workflow -i description.txt -o diagram.svg from archify/bin/archify.mjs.
2. LLM Processing: Archify sends the text to Claude, which returns structured JSON containing nodes for each service and edges representing the communication flows.
3. Schema Validation: The generated JSON is checked against the workflow schema using validators from generate-validators.mjs.
4. SVG Generation: render-workflow.mjs calculates coordinates, creates SVG shapes for nodes, draws arrows for edges, and writes the final diagram.svg file.

The result is a professional diagram reflecting the original English description without manual layout.

Implementation: CLI and Programmatic APIs

Archify exposes both command-line and programmatic interfaces, with entry points at archify/bin/archify.mjs and the @archify/core package respectively.

Command-Line Interface

The CLI entry point orchestrates the entire pipeline, parsing arguments, managing the LLM call, and coordinating validation and rendering.

# Plain-English description in description.txt

archify render workflow -i description.txt -o diagram.svg

Programmatic Integration (Node.js)

For embedding in applications, Archify exposes a render function from @archify/core that handles the complete pipeline internally, accepting the diagram type and plain English description as parameters.

import { render } from '@archify/core';
import fs from 'fs';

// Plain-English description string
const description = `
A front-end service talks to an API gateway.
The gateway forwards to an auth service and a product catalog.
`;

// Generate diagram (the render function handles LLM, validation, and rendering)
const { svg } = await render('workflow', { plainEnglish: description });

await fs.promises.writeFile('diagram.svg', svg);

Extending With Custom Render Hooks

Developers can intercept the rendering process to inject custom SVG elements by importing specific renderer modules directly from archify/renderers/.

import { renderWorkflow } from 'archify/renderers/workflow/render-workflow.mjs';
import fs from 'fs';

export async function renderWithFooter(type, data, outPath) {
  const { svg } = await renderWorkflow({ diagram: data, outPath });
  const footer = `<text x="10" y="${data.meta?.viewBox?.[1] || 800}" font-size="12">Generated by Archify</text>`;
  await fs.promises.writeFile(outPath, svg.replace('</svg>', `${footer}</svg>`));
}

Summary

• Archify uses Claude to parse plain English into JSON structures defined in archify/schemas/*.schema.json.
• archify/scripts/generate-validators.mjs creates runtime validators ensuring schema compliance before rendering.
• Diagram-specific renderers like archify/renderers/workflow/render-workflow.mjs handle layout calculation and SVG generation.
• The CLI at archify/bin/archify.mjs and the @archify/core package provide flexible interfaces for both command-line and programmatic usage.

Frequently Asked Questions

What LLM does Archify use to generate diagrams from plain English?

Archify uses Claude as its language model skill to interpret natural language descriptions. The model processes the input text and outputs structured JSON that conforms to Archify's schema definitions, eliminating the need for manual diagram creation.

How does Archify validate the generated diagram structure?

Validation occurs through validators automatically generated by archify/scripts/generate-validators.mjs. These validators check the LLM-generated JSON against JSON schemas (located in archify/schemas/) to ensure required fields like meta.title, lanes, and nodes are present and that all identifiers are unique.

Can I customize the SVG output or create custom diagram types?

Yes. While Archify provides standard renderers like render-workflow.mjs in archify/renderers/, you can extend functionality by importing specific renderer modules and modifying the SVG output before writing to disk. The modular architecture allows for custom layout engines and template modifications.

Is Archify available as a library or only as a CLI tool?

Archify supports both interfaces. The archify/bin/archify.mjs CLI handles file I/O and command-line arguments, while the @archify/core package exposes a programmatic render function that accepts diagram types and plain English strings, returning SVG content suitable for integration into web applications or documentation pipelines.

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