` tags for accessibility. The renderer respects explicit coordinates when provided in the IR, or delegates to a deterministic layout engine (such as dagre) when positions are omitted. The output is pure SVG markup with embedded CSS classes for theming, requiring no external rendering dependencies. ## Embedding Diagrams in HTML The final stage injects the generated SVG into a web page. Archify provides `archify/renderers/render-mount.mjs` as a lightweight helper that: 1. Locates the JSON IR (inline `<script>` block or fetched resource) 2. Validates and parses the IR 3. Invokes `renderDiagram(ir, container)` to produce SVG 4. Appends the result to a specified DOM container This design produces **zero-install diagrams** — the resulting HTML file contains only vanilla JavaScript and self-contained SVG, with no build-step dependencies for viewers. ### Browser Integration Example ```html <script type="application/json" id="archify-ir"> { "schema_version": 1, "nodes": [ {"id":"agents","type":"agent","label":"Agents"}, {"id":"ir","type":"messagebus","label":"JSON IR","sublabel":"schema v1"} ], "edges": [ {"from":"agents","to":"ir","label":"write IR"} ] } </script> <div id="archify-root"></div> <script type="module"> import { renderDiagram } from '@tt-a1i/archify'; const ir = JSON.parse(document.getElementById('archify-ir').textContent); renderDiagram(ir, document.getElementById('archify-root')); </script> ``` The `renderDiagram` function handles validation caching, renderer instantiation, and DOM insertion in a single call. ## Server-Side and CLI Rendering The same pipeline operates outside the browser for documentation builds and CI artifacts. The `renderDiagramSync` function in `archify/renderers/svg-renderer.mjs` provides synchronous rendering for Node.js environments. ```js import { readFileSync, writeFileSync } from 'node:fs'; import { renderDiagramSync } from '@tt-a1i/archify/renderers/svg-renderer.mjs'; const ir = JSON.parse(readFileSync('examples/archify-repo.architecture.json', 'utf-8')); const svg = renderDiagramSync(ir); writeFileSync('dist/diagram.svg', svg); ``` This enables headless generation of architecture diagrams as part of automated documentation pipelines. ## Key Implementation Files | File | Purpose | |------|---------| | [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) | JSON-Schema definition for IR validation | | `archify/renderers/validate-ir.mjs` | AJV-based validation wrapper | | `archify/renderers/svg-renderer.mjs` | Core SVG generation logic | | `archify/renderers/render-mount.mjs` | Browser mounting helper | | [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html) | Full demo page showing end-to-end transformation | | [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) | Sample IR illustrating schema conventions | ## Summary - **Validation first**: All JSON IR is checked against [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) using AJV before rendering - **Typed SVG generation**: `archify/renderers/svg-renderer.mjs` converts validated IR into accessible `<g>` and `<path>` elements with data attributes - **Flexible embedding**: Browser apps use `renderDiagram()`, while server contexts call `renderDiagramSync()` - **Deterministic output**: Explicit coordinates or seeded layout ensures reproducible diagrams for version control comparison - **Zero dependencies**: Generated HTML/SVG requires no external libraries to display ## Frequently Asked Questions ### What is JSON IR in Archify? **JSON IR (Intermediate Representation)** is a typed, schema-versioned format that describes architecture diagrams as structured data. It encodes nodes with identifiers, types, labels, and positions, plus edges defining relationships. According to the [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) source code, the current `schema_version` is `1`, and the format requires fields like `id`, `type`, `label`, `row`, and `col` for valid node definitions. ### How does Archify validate the JSON IR before rendering? Validation occurs through **AJV** (Another JSON Schema Validator) as implemented in `archify/renderers/validate-ir.mjs`. The validator loads [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) and checks that the input IR conforms to all required fields, correct types, and structural constraints. Invalid IR triggers descriptive error messages before any rendering begins, preventing broken diagrams from reaching output. ### Can Archify render diagrams without a browser? Yes. The `renderDiagramSync` function exported from `archify/renderers/svg-renderer.mjs` operates in **Node.js environments without DOM dependencies**. It returns SVG markup as a string, suitable for writing to files, embedding in static site generators, or serving through documentation APIs. This server-side capability uses the same validation and rendering pipeline as the browser implementation. ### What makes Archify's output deterministic for version control? The JSON IR supports **explicit coordinate fields** (`row`, `col`, or `position` objects) that bypass layout calculation. When coordinates are embedded in the IR, the renderer places elements identically on every run. For layouts requiring computation, Archify uses seeded deterministic algorithms rather than stochastic layout engines, ensuring that identical IR produces pixel-identical SVG output suitable for diff-based version control workflows.

# How Archify Transforms JSON IR into HTML and SVG Diagrams > Learn how Archify transforms JSON IR into HTML and SVG diagrams using a three-stage pipeline: schema validation, typed rendering, and HTML embedding. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-09-01 --- **Archify transforms JSON IR into HTML/SVG diagrams through a three-stage pipeline: schema validation with AJV, typed rendering to SVG elements, and HTML embedding via a lightweight bootstrap script.** The **JSON Intermediate Representation (IR)** is the core data structure that powers Archify's architecture visualization toolkit. This typed format captures nodes, edges, layout coordinates, and visual styling in a deterministic, version-controlled schema. The transformation from raw JSON IR to browser-ready diagrams follows a clean separation between validation, rendering, and mounting concerns. ## Understanding the JSON IR Schema Before any rendering occurs, Archify validates the JSON IR against a strict **JSON-Schema** definition. This ensures structural integrity and provides clear error messages when the IR deviates from expectations. The schema requires fields such as `id`, `type`, `label`, `row`, and `col` for nodes, with optional modifiers like `sublabel`, `position`, and `style`. The `schema_version` field (currently version `1`) enables safe evolution of the format across releases. ```json { "schema_version": 1, "nodes": [ {"id":"agents","type":"agent","label":"Agents"}, {"id":"ir","type":"messagebus","label":"JSON IR","sublabel":"schema v1"} ], "edges": [ {"from":"agents","to":"ir","label":"write IR"} ] } ``` The validation layer resides in [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) and is invoked by `archify/renderers/validate-ir.mjs` using the **AJV** validator. ## The SVG Rendering Pipeline Once validated, the IR flows into the **typed renderer** implemented in `archify/renderers/svg-renderer.mjs`. This module walks the IR structure and constructs SVG elements programmatically. **Node rendering** creates `` container elements with standardized data attributes: - `data-node-id` — the node's unique identifier - `data-node-label` — display text for tooltips - `data-node-type` — visual classification (agent, service, database, etc.) **Edge rendering** generates `` elements with arrow markers and optional `` tags for accessibility. The renderer respects explicit coordinates when provided in the IR, or delegates to a deterministic layout engine (such as dagre) when positions are omitted. The output is pure SVG markup with embedded CSS classes for theming, requiring no external rendering dependencies. ## Embedding Diagrams in HTML The final stage injects the generated SVG into a web page. Archify provides `archify/renderers/render-mount.mjs` as a lightweight helper that: 1. Locates the JSON IR (inline `<script>` block or fetched resource) 2. Validates and parses the IR 3. Invokes `renderDiagram(ir, container)` to produce SVG 4. Appends the result to a specified DOM container This design produces **zero-install diagrams** — the resulting HTML file contains only vanilla JavaScript and self-contained SVG, with no build-step dependencies for viewers. ### Browser Integration Example ```html <script type="application/json" id="archify-ir"> { "schema_version": 1, "nodes": [ {"id":"agents","type":"agent","label":"Agents"}, {"id":"ir","type":"messagebus","label":"JSON IR","sublabel":"schema v1"} ], "edges": [ {"from":"agents","to":"ir","label":"write IR"} ] } </script> <div id="archify-root"></div> <script type="module"> import { renderDiagram } from '@tt-a1i/archify'; const ir = JSON.parse(document.getElementById('archify-ir').textContent); renderDiagram(ir, document.getElementById('archify-root')); </script> ``` The `renderDiagram` function handles validation caching, renderer instantiation, and DOM insertion in a single call. ## Server-Side and CLI Rendering The same pipeline operates outside the browser for documentation builds and CI artifacts. The `renderDiagramSync` function in `archify/renderers/svg-renderer.mjs` provides synchronous rendering for Node.js environments. ```js import { readFileSync, writeFileSync } from 'node:fs'; import { renderDiagramSync } from '@tt-a1i/archify/renderers/svg-renderer.mjs'; const ir = JSON.parse(readFileSync('examples/archify-repo.architecture.json', 'utf-8')); const svg = renderDiagramSync(ir); writeFileSync('dist/diagram.svg', svg); ``` This enables headless generation of architecture diagrams as part of automated documentation pipelines. ## Key Implementation Files | File | Purpose | |------|---------| | [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) | JSON-Schema definition for IR validation | | `archify/renderers/validate-ir.mjs` | AJV-based validation wrapper | | `archify/renderers/svg-renderer.mjs` | Core SVG generation logic | | `archify/renderers/render-mount.mjs` | Browser mounting helper | | [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html) | Full demo page showing end-to-end transformation | | [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) | Sample IR illustrating schema conventions | ## Summary - **Validation first**: All JSON IR is checked against [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) using AJV before rendering - **Typed SVG generation**: `archify/renderers/svg-renderer.mjs` converts validated IR into accessible `<g>` and `<path>` elements with data attributes - **Flexible embedding**: Browser apps use `renderDiagram()`, while server contexts call `renderDiagramSync()` - **Deterministic output**: Explicit coordinates or seeded layout ensures reproducible diagrams for version control comparison - **Zero dependencies**: Generated HTML/SVG requires no external libraries to display ## Frequently Asked Questions ### What is JSON IR in Archify? **JSON IR (Intermediate Representation)** is a typed, schema-versioned format that describes architecture diagrams as structured data. It encodes nodes with identifiers, types, labels, and positions, plus edges defining relationships. According to the [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) source code, the current `schema_version` is `1`, and the format requires fields like `id`, `type`, `label`, `row`, and `col` for valid node definitions. ### How does Archify validate the JSON IR before rendering? Validation occurs through **AJV** (Another JSON Schema Validator) as implemented in `archify/renderers/validate-ir.mjs`. The validator loads [`archify/schema/ir-schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/ir-schema.json) and checks that the input IR conforms to all required fields, correct types, and structural constraints. Invalid IR triggers descriptive error messages before any rendering begins, preventing broken diagrams from reaching output. ### Can Archify render diagrams without a browser? Yes. The `renderDiagramSync` function exported from `archify/renderers/svg-renderer.mjs` operates in **Node.js environments without DOM dependencies**. It returns SVG markup as a string, suitable for writing to files, embedding in static site generators, or serving through documentation APIs. This server-side capability uses the same validation and rendering pipeline as the browser implementation. ### What makes Archify's output deterministic for version control? The JSON IR supports **explicit coordinate fields** (`row`, `col`, or `position` objects) that bypass layout calculation. When coordinates are embedded in the IR, the renderer places elements identically on every run. For layouts requiring computation, Archify uses seeded deterministic algorithms rather than stochastic layout engines, ensuring that identical IR produces pixel-identical SVG output suitable for diff-based version control workflows.