The Five Stages of the Archify Rendering Pipeline Explained

Archify transforms plain‑English descriptions into production‑ready diagrams through five discrete stages—Generate JSON IR, Validate, Render, Check, and Iterate—each implemented as a standalone operation in the tt-a1i/archify codebase.

The tt-a1i/archify repository provides a robust framework for architecture visualization that converts natural language into structured SVG artifacts. Understanding the five stages of the Archify rendering pipeline helps developers trace how an abstract concept becomes a validated, self‑contained HTML file.

The Five Stages Explained

Archify processes diagrams through a repeatable pipeline defined in the How it works section of the repository README. Each stage handles a specific transformation from intermediate representation to final artifact.

1. Generate JSON IR

The pipeline begins when the agent or CLI creates a typed JSON Intermediate Representation (IR) that describes the diagram structure. Rather than hand‑editing SVG markup, users define architecture, workflow, sequence, data‑flow, or lifecycle diagrams as structured JSON. The schemas defining these types are documented in archify/schemas/README.md, ensuring consistent data models across diagram categories.

2. Validate

Stand‑alone validators bundled with the skill check the JSON IR against the appropriate schema. This stage verifies required fields, correct data types, and structural integrity before rendering begins. According to the source code, the validate function enforces these constraints programmatically, preventing invalid configurations from reaching the renderer.

3. Render

The selected renderer consumes the validated JSON IR and produces the final artifact as self‑contained HTML with embedded SVG. The implementation for architecture diagrams resides in archify/renderers/architecture/README.md, with parallel implementations for workflow, sequence, data‑flow, and lifecycle diagram types. This separation of concerns allows the rendering logic to evolve independently of the input format.

4. Check

Layout and artifact validation runs on the generated HTML/SVG to catch geometric errors, malformed markup, or unsafe arrow routes. The check function analyzes coordinate validity and SVG structure, ensuring the output meets quality standards before delivery. This stage acts as a final safety net for visual correctness.

5. Iterate

If the check stage reports problems or the user requests modifications, targeted edits are applied to the JSON IR. The pipeline then loops back to the Validate stage (stage 2), creating an efficient revision cycle without requiring a full regeneration from scratch. The iterate function handles these incremental updates, preserving context while applying specific changes.

CLI and Programmatic Implementation

The archify/bin/archify.mjs file serves as the CLI entry point that orchestrates these five stages. Developers can invoke the pipeline via command line or import the stage functions directly into Node.js applications.

Use the CLI to walk through the pipeline manually:

# Stage 1: Generate JSON IR (implicit in render or explicit creation)

node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html

# Stage 2: Validate the JSON IR explicitly

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json

# Stage 4: Check the generated HTML/SVG for layout problems

node bin/archify.mjs check /tmp/workflow.html

# Stage 5: Iterate by editing the JSON and re‑running validation and rendering

For programmatic use inside skills or applications, import the stage functions directly:

import { generateIR, validate, render, check, iterate } from 'archify';

// Stage 1: Generate IR from natural language
const ir = await generateIR('workflow', userPrompt);

// Stage 2: Validate structure
await validate('workflow', ir);

// Stage 3: Render to HTML
const html = await render('workflow', ir);

// Stage 4: Check for errors
await check(html);

// Stage 5: Iterate if feedback requires changes
const updatedIr = await iterate(ir, userFeedback);

Unit tests in archify/test/*.test.mjs verify each stage independently, ensuring that generation, validation, rendering, checking, and iteration logic function correctly across diagram types.

Summary

• The Archify rendering pipeline consists of five sequential stages: Generate JSON IR, Validate, Render, Check, and Iterate.
• Each stage is implemented as a discrete function (generateIR, validate, render, check, iterate) in the tt-a1i/archify codebase.
• The CLI entry point at archify/bin/archify.mjs orchestrates these stages for command‑line workflows.
• Validation occurs twice: once against JSON schemas in archify/schemas/README.md and again as layout checking on the final SVG.
• The iteration loop restarts from stage 2, enabling efficient revisions without full regeneration.

Frequently Asked Questions

What file format does the Archify rendering pipeline output?

The pipeline produces self‑contained HTML files with embedded SVG markup. The render stage generates these artifacts after the JSON IR passes validation, resulting in portable diagrams that require no external dependencies to display in browsers.

How does the Validate stage enforce data integrity?

The validate function checks the JSON IR against strict schemas defined in archify/schemas/README.md, verifying required fields and data types. This prevents malformed intermediate representations from reaching the rendering engines, catching structural errors before they become visual artifacts.

Can developers restart the pipeline from a specific stage?

Yes. The Iterate stage allows targeted modifications to the JSON IR, after which the pipeline loops back to the Validate stage rather than regenerating the initial IR. This design enables rapid refinement cycles when adjusting diagram layouts or correcting minor content errors.

Where is the rendering logic implemented for architecture diagrams?

The Render stage implementation for architecture diagrams is documented in archify/renderers/architecture/README.md, with similar renderer documentation existing for workflow, sequence, data‑flow, and lifecycle diagram types. These files define how the validated JSON IR translates into specific SVG geometries and layout algorithms.

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