# The Five Stages of the Archify Rendering Pipeline Explained

> Understand the Archify rendering pipeline's five stages: Generate JSON IR, Validate, Render, Check, and Iterate. Transform plain English into production-ready diagrams with Archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-15

---

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

```bash

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

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