# How Archify's JSON IR Powers the Rendering Pipeline

> Discover how Archify's JSON IR fuels the rendering pipeline. Learn about schema validation, typed renderer selection, and deterministic layout for standalone HTML diagrams.

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

---

**Archify converts a typed, version-controlled JSON Intermediate Representation (IR) into standalone HTML diagrams through schema validation, typed renderer selection, and deterministic layout validation.**

The `tt-a1i/archify` repository implements a robust diagram generation system centered on a JSON IR that ensures reproducible, schema-validated outputs. Understanding how this Archify JSON IR flows through the rendering pipeline reveals why the tool produces deterministic, self-contained HTML artifacts from pure JSON descriptions.

## The JSON IR Structure

Every Archify diagram begins as a JSON file that must include two mandatory top-level fields: `schema_version: 1` and `diagram_type`. The IR describes components, connections, metadata, and layout hints that drive the final visualization. A canonical example lives in [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json), which demonstrates the required fields, component definitions, and the "cards" section that structures the HTML output.

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { 
    "title": "Archify", 
    "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML" 
  },
  "components": [],
  "connections": []
}

```

## Step-by-Step Rendering Pipeline

### Reading the Versioned IR

The pipeline begins by reading the JSON IR file from disk. The entry point validates that the required fields `schema_version` and `diagram_type` exist before proceeding. This step is visualized in the gallery page at [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html), which documents the flow from JSON input to renderer execution.

### Schema Validation with AJV

Once loaded, the IR undergoes strict validation against a JSON-Schema using AJV validators generated in `generated-validators.mjs`. The `validateSchema` function in `archify/renderers/shared/validator.mjs` loads the appropriate validator for the specific `diagram_type` and runs the validation. If the IR violates the schema, the function throws a diagnostic error immediately.

```javascript
// From archify/renderers/shared/validator.mjs
validateSchema(diagramType, jsonData) {
  const validator = this.validators.get(diagramType);
  const valid = validator(jsonData);
  if (!valid) {
    throw new Error(`Schema validation failed: ${JSON.stringify(validator.errors)}`);
  }
}

```

### Typed Renderer Selection

The `diagram_type` field determines which of the five typed renderers handles the diagram: **architecture**, **workflow**, **sequence**, **dataflow**, or **lifecycle**. Each renderer implements specialized layout and geometry logic while sharing common utilities. For architecture diagrams, the main entry point is `archify/renderers/architecture/render-architecture.mjs`, which orchestrates the entire rendering process from lines 53-57.

### Layout Computation and Validation

After selecting the renderer, the system computes component positions, connection routes, and boundaries. The architecture renderer then runs a series of "clean" validation gates to ensure deterministic geometry and spacing. The `validateArchitecture()` function invokes checks like `cleanFlowProblems` and `cleanCrossingProblems` to verify that the layout meets stability requirements.

```javascript
// Validation gates inside render-architecture.mjs
validateArchitecture(layout) {
  this.cleanFlowProblems(layout);
  this.cleanCrossingProblems(layout);
  // Additional geometry checks...
}

```

### Final Output Generation

Once the IR passes both schema and layout validation, the renderer constructs an SVG and wraps it in [`template.html`](https://github.com/tt-a1i/archify/blob/main/template.html). The `archify/renderers/shared/cli.mjs` module handles writing the standalone HTML file, with calls originating from `render-architecture.mjs` after successful validation. The pipeline also supports optional PNG and WebM exports.

## CLI Usage and Examples

Render a diagram directly from the JSON IR using Node.js:

```bash
node archify/renderers/architecture/render-architecture.mjs \
  --diagram examples/archify-repo.architecture.json \
  --outPath out.html

```

Generate a JSON-only layout report for downstream tooling without producing HTML:

```bash
node archify/renderers/architecture/render-architecture.mjs \
  --diagram examples/archify-repo.architecture.json \
  --layout-json

```

## Summary

- **Archify JSON IR** requires `schema_version: 1` and `diagram_type` fields to ensure version compatibility and renderer selection.
- The **AJV-based validator** in `archify/renderers/shared/validator.mjs` enforces schema correctness before rendering begins.
- **Typed renderers** handle specific diagram types (architecture, workflow, sequence, dataflow, lifecycle) with specialized logic.
- **Layout validation gates** like `cleanFlowProblems` guarantee deterministic geometry and prevent rendering artifacts.
- The pipeline outputs **standalone HTML artifacts** via `archify/renderers/shared/cli.mjs`, with optional layout JSON exports available via CLI flags.

## Frequently Asked Questions

### What are the mandatory fields in an Archify JSON IR file?

Every JSON IR file must include `schema_version` set to `1` and a `diagram_type` string that specifies which renderer to invoke (such as "architecture" or "workflow"). These fields ensure the pipeline selects the correct validator and layout engine.

### How does Archify validate the JSON IR before rendering?

Archify uses AJV validators defined in `generated-validators.mjs`. The `validateSchema` function in `archify/renderers/shared/validator.mjs` loads the schema for the specified `diagram_type` and throws a diagnostic error if the input JSON violates any schema constraints.

### Can I extract just the layout data without generating HTML?

Yes. Passing the `--layout-json` flag to any renderer CLI (such as `render-architecture.mjs`) outputs a JSON description of the computed component positions and connection routes without writing the HTML artifact, useful for integrating with external tooling.

### What happens if the layout validation fails?

If geometry checks like `cleanFlowProblems` or `cleanCrossingProblems` detect issues during `validateArchitecture()`, the pipeline halts and reports diagnostic information. This ensures that every generated diagram meets Archify's deterministic spacing and routing standards.