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

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:

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 to enforce version constraints and consistent packaging.

Install Into Your Workspace

Copy the generated ZIP to your Instagit skills directory:

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:

{
  "$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.

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 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 contains a placeholder for your IR:

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

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

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

# 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; 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	Self-contained diagram renderer with [[START_JSON]] placeholder	scripts/start-template.html
examples/web-app.architecture.json	Production-ready example IR with full type coverage	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	CI wrapper enforcing version constraints	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 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 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. 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?

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 is a CI-friendly wrapper that invokes the ZIP builder while enforcing version constraints and exit-code handling suitable for automated pipelines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}