# What is the Archify Rendering Pipeline? A Deep Dive into the 8-Stage JSON-to-HTML Process

> Explore the Archify rendering pipeline. Learn how this 8-stage process converts JSON IR to HTML diagrams, detailing CLI parsing, schema validation, and rendering techniques.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-07-20

---

**The Archify rendering pipeline transforms a JSON intermediate representation (IR) into a self-contained HTML diagram by chaining together CLI parsing, schema validation, type-specific renderers, geometric layout algorithms, and template injection.**

The **Archify rendering pipeline** powers the `tt-a1i/archify` open-source project, converting declarative JSON diagram definitions into polished, interactive HTML visualizations. Written in Node.js, this eight-stage toolchain validates structural correctness, calculates geometric layouts, and generates standalone SVG-based diagrams without requiring external rendering dependencies.

## The 8 Stages of the Archify Rendering Pipeline

The pipeline follows a strict sequence from CLI invocation to final HTML output, with each stage handled by specific modules in the repository.

### 1. CLI Entry Point and Command Dispatch

The process begins in `archify/bin/archify.mjs`, where the `commandRender` function (lines 54‑58) parses the command-line arguments. This entry point extracts the diagram type (e.g., `architecture`, `lifecycle`), input JSON path, and optional output destination, then dispatches to the appropriate handler.

```bash
archify render architecture examples/web-app.architecture.json output.html

```

### 2. Diagram Loading and Path Resolution

The `loadDiagram` function in `archify/renderers/shared/cli.mjs` (lines 7‑16) reads the JSON file from disk, resolves absolute paths for the output file, and prepares the diagram object for processing. This stage handles file system operations and ensures the input is readable before validation begins.

```javascript
// Internal flow: loadDiagram reads file → returns diagram object + template path
import { loadDiagram } from './renderers/shared/cli.mjs';
const { diagram, templatePath, outPath } = await loadDiagram(type, inputPath, outputArg);

```

### 3. Schema Validation with AJV

Before rendering, the pipeline validates the JSON structure against pre-generated AJV schemas. The `validateSchema` function in `archify/renderers/shared/validator.mjs` (lines 30‑38) looks up the type-specific validator from `generated-validators.mjs` and throws descriptive errors for structural violations. This prevents malformed diagrams from reaching the layout engine.

```bash

# Human-readable validation output

archify validate lifecycle examples/agent-run.lifecycle.json

# Machine-readable JSON result

archify validate lifecycle examples/agent-run.lifecycle.json --json

```

### 4. Type-Specific Renderer Execution

Based on the diagram type, the pipeline invokes one of the `render-<type>.mjs` modules, such as `archify/renderers/lifecycle/render-lifecycle.mjs` or `archify/renderers/architecture/render-architecture.mjs`. These modules perform four critical substeps:
- **Layout measurement**: Calculating bounding boxes and component dimensions
- **Validation of layout rules**: Ensuring geometric constraints are satisfied
- **Edge routing**: Computing connection paths between elements
- **SVG generation**: Constructing the final `<svg>` string (lines 21‑27, 31‑35, 102‑117, 215‑236 in `render-lifecycle.mjs`)

### 5. Geometric Layout Helpers

Shared utilities in `archify/renderers/shared/` provide mathematical primitives used by all renderers. The `geometry.mjs` module (lines 14‑22) exports functions like `anchor`, `roundedPath`, and `labelPoint` for coordinate arithmetic, while `grid.mjs` handles collision detection and auto-viewBox calculation. These helpers decouple geometric logic from specific diagram types.

```javascript
// Example: Geometry utilities used during layout
import { anchor, roundedPath } from './renderers/shared/geometry.mjs';
const startAnchor = anchor(nodeA, 'right');
const pathData = roundedPath(startAnchor, endAnchor, radius);

```

### 6. HTML Template Injection

The `writeDiagram` function in `archify/renderers/shared/cli.mjs` (lines 19‑30) injects the generated SVG, title, subtitle, footer, and optional info-cards into [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html). This produces a standalone HTML file containing embedded CSS and JavaScript, requiring no external dependencies to display.

### 7. Optional Layout JSON Output

When invoked with the `--layout-json` flag (or via `archify inspect`), the pipeline skips HTML generation and exports the calculated layout as JSON. In `render-architecture.mjs` (lines 26‑34, 60‑63), the renderer calls `buildLayoutReport()` and outputs a JSON payload describing component boxes, connection coordinates, and viewBox dimensions—useful for CI/CD validation and testing.

```bash

# Export layout data for automated testing

archify inspect architecture

```

### 8. Post-Render Validation

The final stage runs when executing `archify check`. The `commandCheck` function in `archify.mjs` (lines 61‑66) invokes `scripts/check-render-output.mjs` to verify SVG well-formedness and ensure all animation steps are present in lifecycle diagrams, catching regressions before deployment.

## Architectural Flow Visualization

The complete pipeline data flow resembles this sequence:

```

archify (CLI) ─► loadDiagram ─► validateSchema ─► render-<type>.mjs
          │                                 │
          │                                 ├─► layout helpers (geometry.mjs, grid.mjs)
          │                                 │
          │                                 └─► SVG string generation
          │
          └─► writeDiagram (template injection) ─► final HTML file

```

## Practical Usage Examples

### Render an Architecture Diagram

Convert a JSON definition to a standalone HTML file:

```bash
archify render architecture examples/web-app.architecture.json output.html

```

This executes the full pipeline: `commandRender` → `loadDiagram` → `render-architecture.mjs` → `writeDiagram`.

### Validate Without Rendering

Check structural and layout correctness without generating output:

```bash
archify validate lifecycle examples/agent-run.lifecycle.json

```

Validation runs the schema checker and temporary rendering pipeline, reporting human-readable errors or JSON machine-readable results when using `--json`.

### Batch Process Examples

Render all bundled example diagrams to verify the installation:

```bash
archify examples

```

This executes `scripts/render-examples.mjs`, which loops over the `TARGETS` array and invokes each type-specific renderer with corresponding sample JSON files.

## Summary

- The **Archify rendering pipeline** consists of eight distinct stages: CLI parsing, diagram loading, schema validation, type-specific rendering, geometric layout calculation, HTML templating, optional JSON export, and post-render verification.
- Key entry points include `archify/bin/archify.mjs` for commands and `archify/renderers/shared/cli.mjs` for the core loading sequence.
- Type-specific renderers like `render-lifecycle.mjs` and `render-architecture.mjs` handle measurement, validation, routing, and SVG construction.
- Shared utilities in `geometry.mjs` and `grid.mjs` provide reusable geometric primitives for coordinate math and collision detection.
- The output is a self-contained HTML file generated by injecting SVG into [`assets/template.html`](https://github.com/tt-a1i/archify/blob/main/assets/template.html), suitable for standalone deployment or CI verification via `--layout-json`.

## Frequently Asked Questions

### How does Archify validate diagram correctness before rendering?

Archify uses **AJV (Another JSON Schema Validator)** through `archify/renderers/shared/validator.mjs`. The `validateSchema` function loads pre-compiled validators from `generated-validators.mjs` specific to each diagram type (architecture, lifecycle, etc.). If validation fails, the pipeline exits with human-readable error messages indicating which JSON properties violate the schema, preventing invalid diagrams from reaching the layout engine.

### Can I extract layout coordinates without generating an HTML file?

Yes. Pass the `--layout-json` flag to the `render` or `validate` commands, or use the `archify inspect <type>` shortcut. This triggers `buildLayoutReport()` in the type-specific renderer (e.g., lines 60‑63 in `render-architecture.mjs`), which outputs a JSON object containing component bounding boxes, connection paths, and viewBox dimensions to stdout instead of writing HTML.

### What layout algorithms does Archify use for component placement?

The pipeline relies on **grid-based layout** and **force-directed geometry** implemented in `archify/renderers/shared/grid.mjs` and `geometry.mjs`. The `render-architecture.mjs` module uses grid snapping for component alignment, while `render-lifecycle.mjs` calculates state positions using relative spacing and validates geometry against minimum distance constraints. The `anchor` function in `geometry.mjs` ensures connection points align to node edges with configurable padding.

### How can I integrate Archify into a CI/CD pipeline?

Use the validation and inspection commands for automated testing. Run `archify validate <type> <file> --json` to receive machine-readable pass/fail results, or `archify inspect <type>` to capture layout JSON for snapshot testing. The `archify check` command runs `scripts/check-render-output.mjs` to verify SVG well-formedness and animation completeness, making it suitable for pre-deployment gates in automated workflows.