# How to Generate System Diagrams from JSON IR Using Archify: A Complete Guide

> Learn to generate system diagrams from JSON IR with Archify. This guide shows how Archify transforms JSON IR into interactive diagrams securely in your browser. Get started today.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Archify transforms typed JSON intermediate representations into interactive, privacy-preserving system diagrams entirely inside the browser without transmitting data to external services.**

Archify is an open-source tool from `tt-a1i/archify` that reads a structured JSON IR (intermediate representation) of your system architecture and renders it as an interactive diagram. This guide walks through the complete workflow from installation to rendered output, using the actual source files and build scripts from the repository.

## Install the Archify Skill

Before generating diagrams, you need the Archify skill installed in your workspace. The repository provides a deterministic ZIP builder and installation scripts.

### Build the Distribution ZIP

Run the build script from the repository root:

```bash
npm run build-zip

```

This invokes `scripts/write-deterministic-zip.mjs`, which creates `archify.zip` with reproducible contents. The same script runs in CI via [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) to enforce version constraints and consistent packaging.

### Install Into Your Workspace

Copy the generated ZIP to your Instagit skills directory:

```bash
mkdir -p ~/.raven/workspace/skills/archify
cp archify.zip ~/.raven/workspace/skills/archify/

```

The skill is now available for loading into your workspace.

## Prepare the JSON IR File

Archify requires a JSON IR that conforms to its typed schema. The schema is enforced at runtime by the skill's internal validator.

### IR File Structure

Create a file following this structure, referencing the official schema:

```json
{
  "$schema": "https://tt-a1i.github.io/archify/schemas/architecture.json",
  "nodes": [
    { "id": "frontend", "kind": "frontend", "label": "Web UI" },
    { "id": "api",      "kind": "backend",  "label": "API Service" },
    { "id": "db",       "kind": "database", "label": "PostgreSQL" }
  ],
  "edges": [
    { "source": "frontend", "target": "api", "label": "HTTPS" },
    { "source": "api",      "target": "db",  "label": "SQL" }
  ]
}

```

Save this as [`my-system.architecture.json`](https://github.com/tt-a1i/archify/blob/main/my-system.architecture.json).

### Schema Validation

The `$schema` property points to Archify's type definition, ensuring the IR passes validation before rendering. For a complete working example, see [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) in the repository, which demonstrates a fully-typed three-tier web application.

## Render the Diagram from JSON IR

Archify generates diagrams through **zero-dependency client-side rendering** inside a self-contained HTML page.

### Method 1: Embed JSON Directly in the Template

The file [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) contains a placeholder for your IR:

```html
<script id="start-data" type="application/json">[[START_JSON]]</script>

```

Replace `[[START_JSON]]` with your IR contents using a simple substitution script:

```bash
node -e "
const fs = require('fs');
const json = fs.readFileSync('my-system.architecture.json', 'utf8');
const tmpl = fs.readFileSync('scripts/start-template.html', 'utf8');
const html = tmpl.replace('[[START_JSON]]', json);
fs.writeFileSync('my-diagram.html', html);
"

```

Open [`my-diagram.html`](https://github.com/tt-a1i/archify/blob/main/my-diagram.html) in any browser to view the interactive diagram.

### Method 2: URL Parameter Injection

Alternatively, URL-encode your JSON and append it to [`start-template.html`](https://github.com/tt-a1i/archify/blob/main/start-template.html):

```bash

# URL-encode the JSON IR

ENCODED=$(node -e "console.log(encodeURIComponent(require('fs').readFileSync('my-system.architecture.json')))")

# Open with data parameter

open "scripts/start-template.html?data=${ENCODED}"

```

The page's JavaScript automatically detects the `?data=` parameter, decodes it, and populates the hidden script tag before rendering.

## Privacy and Security Architecture

Archify's rendering pipeline guarantees **no repository or diagram data leaves the user's session**:

- **Self-contained execution**: All JavaScript required for diagram generation ships inside [`start-template.html`](https://github.com/tt-a1i/archify/blob/main/start-template.html); no CDN requests are made
- **Verified provenance**: The skill's internal validator checks JSON against TypeScript type definitions before rendering
- **Zero external transmission**: The start page explicitly states "no repository content or diagram data is sent to this page" — a guarantee enforced by the browser-local architecture

## Key Source Files Reference

| File | Purpose | Location |
|------|---------|----------|
| [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | Self-contained diagram renderer with `[[START_JSON]]` placeholder | [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) |
| [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) | Production-ready example IR with full type coverage | [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) |
| `scripts/write-deterministic-zip.mjs` | Builds reproducible `archify.zip` for skill distribution | `scripts/write-deterministic-zip.mjs` |
| [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) | CI wrapper enforcing version constraints | [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) |

## Summary

- **Install** the Archify skill using `npm run build-zip` and copy `archify.zip` to your workspace
- **Author** a JSON IR file referencing `$schema: https://tt-a1i.github.io/archify/schemas/architecture.json`
- **Render** via [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) by substituting `[[START_JSON]]` or using URL parameter injection
- **Preserve privacy** through zero-dependency browser-local rendering with no external data transmission

## Frequently Asked Questions

### What format does the JSON IR need to follow?

The JSON IR must conform to Archify's typed schema, referenced via `"$schema": "https://tt-a1i.github.io/archify/schemas/architecture.json"`. The schema requires `nodes` (array of typed components) and `edges` (array of connectivity relationships). The skill's internal validator enforces these types at runtime before rendering. See [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) for a complete, valid example.

### Does Archify send my diagram data to external servers?

No. Archify renders diagrams entirely client-side using the self-contained [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html). All JavaScript required for diagram generation is bundled in the page; no CDN calls or external API requests are made. The start page explicitly guarantees that "no repository content or diagram data is sent to this page."

### How do I distribute diagrams to teammates without installing Archify?

Generate a standalone HTML file using the `[[START_JSON]]` substitution method. The resulting `.html` file contains both the renderer and your IR data, making it fully portable — recipients can open it in any browser without installing the skill or running any build tools.

### What is the difference between `write-deterministic-zip.mjs` and [`build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/build-zip.sh)?

`scripts/write-deterministic-zip.mjs` is the core ZIP builder that creates reproducible `archify.zip` archives with deterministic file ordering and timestamps. [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) is a CI-friendly wrapper that invokes the ZIP builder while enforcing version constraints and exit-code handling suitable for automated pipelines.