# Archify JSON IR Schema Structure: Complete Reference Guide

> Explore the Archify JSON IR schema structure for defining architecture diagrams data-flow graphs and workflows. Understand its components connections metadata and more in this comprehensive guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-02

---

**The Archify JSON IR schema is a declarative intermediate representation that defines architecture diagrams, data-flow graphs, and workflows through a standardized top-level object containing schema version, diagram type, metadata, components, connections, and optional boundaries and cards.**

The **Archify JSON IR** (Intermediate Representation) is the core serialization format used by the `tt-a1i/archify` project to store, validate, and render technical diagrams. Every JSON IR file follows a strict schema that enables the Archify compiler to generate interactive HTML/SVG visualizations. This guide breaks down every property, field, and optional extension based on the actual source code implementation.

---

## Core Schema Properties

Every Archify JSON IR object requires these six top-level properties, with two being optional:

| Property | Type | Required | Purpose |
|----------|------|----------|---------|
| `schema_version` | integer | Yes | Schema compatibility marker (current: `1`) |
| `diagram_type` | string | Yes | Diagram category: `"architecture"`, `"workflow"`, `"dataflow"`, or `"sequence"` |
| `meta` | object | Yes | Human-readable titles, subtitles, and output paths |
| `components` | array | Yes | Node definitions with position, size, and styling |
| `boundaries` | array | No | Visual grouping regions around components |
| `connections` | array | Yes | Directed edges between components |
| `cards` | array | No | Sidebar information panels |

---

## Metadata Section (`meta`)

The `meta` object controls presentation and output generation:

```json
{
  "meta": {
    "title": "Sample System",
    "subtitle": "Demo of the Archify JSON IR",
    "output": "examples/sample-arch.html"
  }
}

```

- **`title`** – Main heading displayed above the diagram
- **`subtitle`** – Secondary descriptive text
- **`output`** – Destination path for generated HTML (relative to project root)

---

## Components Array

Components are the visual nodes in your diagram. Each component in the `components` array requires six core fields:

### Required Component Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier referenced by connections |
| `type` | string | Styling classification: `"frontend"`, `"backend"`, `"cloud"`, `"external"`, `"database"`, `"messagebus"`, `"security"` |
| `label` | string | Primary display name on the node |
| `sublabel` | string | Secondary description (technology stack, version, etc.) |
| `pos` | `[x, y]` | Pixel coordinates of top-left corner |
| `size` | `[width, height]` | Node dimensions in pixels |

### Optional Component Fields

- **`tag`** – Free-form string for custom styling hooks
- **`row`** / **`col`** – Grid-based placement for auto-layout diagrams (see [[`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json)](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json))

```json
{
  "components": [
    {
      "id": "backend",
      "type": "backend",
      "label": "API",
      "sublabel": "Node.js",
      "pos": [380, 200],
      "size": [140, 60],
      "tag": "critical-path"
    }
  ]
}

```

---

## Boundaries Array (Optional)

**Boundaries** create visual grouping regions around components. As implemented in the Maka example at [[`examples/maka-architecture.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json)](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json), each boundary contains:

| Field | Type | Description |
|-------|------|-------------|
| `kind` | string | `"region"` for logical groups or `"security-group"` for trust boundaries |
| `label` | string | Description shown on the boundary |
| `wraps` | string[] | Array of component `id`s to enclose |

```json
{
  "boundaries": [
    {
      "kind": "region",
      "label": "Electron app + packages/runtime",
      "wraps": ["ui", "main", "session", "agentrun", "model", "toolrt", "storage", "permission"]
    },
    {
      "kind": "security-group",
      "label": "trust boundary",
      "wraps": ["permission", "storage"]
    }
  ]
}

```

---

## Connections Array

**Connections** define directed edges between components with extensive visual customization:

### Required Connection Fields

| Field | Type | Description |
|-------|------|-------------|
| `from` | string | Source component `id` |
| `to` | string | Destination component `id` |

### Optional Visual Modifiers

| Field | Type | Description |
|-------|------|-------------|
| `label` | string | Text displayed on the edge |
| `variant` | string | Line style: `"emphasis"`, `"dashed"`, `"security"` |
| `fromSide` / `toSide` | string | Anchor point: `"top"`, `"bottom"`, `"left"`, `"right"` |
| `via` | `[[x, y], ...]` | Poly-line routing waypoints |

```json
{
  "connections": [
    {
      "from": "frontend",
      "to": "backend",
      "label": "HTTP",
      "variant": "emphasis",
      "fromSide": "right",
      "toSide": "left"
    }
  ]
}

```

---

## Cards Array (Optional)

**Cards** render as sidebar information panels for contextual documentation:

| Field | Type | Description |
|-------|------|-------------|
| `dot` | string | Leading bullet color (e.g., `"cyan"`, `"red"`, `"green"`) |
| `title` | string | Card header |
| `items` | string[] | Bullet-point content strings |

```json
{
  "cards": [
    {
      "dot": "cyan",
      "title": "Desktop surfaces",
      "items": [
        "apps/desktop: renderer, preload, main process",
        "Settings for models, bots, search, gateway, permissions",
        "Bots and open gateway share SessionManager as the public API"
      ]
    }
  ]
}

```

---

## Complete Minimal Example

This valid Archify JSON IR demonstrates all required fields:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample System",
    "subtitle": "Demo of the Archify JSON IR",
    "output": "examples/sample-arch.html"
  },
  "components": [
    { "id": "client",   "type": "external", "label": "Client",   "sublabel": "Browser",     "pos": [40, 200],  "size": [120, 60] },
    { "id": "frontend", "type": "frontend", "label": "UI",       "sublabel": "React",       "pos": [200, 200], "size": [140, 60] },
    { "id": "backend",  "type": "backend",  "label": "API",      "sublabel": "Node.js",     "pos": [380, 200], "size": [140, 60] },
    { "id": "db",       "type": "database", "label": "Database", "sublabel": "PostgreSQL",  "pos": [580, 200], "size": [140, 60] }
  ],
  "connections": [
    { "from": "client",   "to": "frontend", "variant": "emphasis" },
    { "from": "frontend", "to": "backend",  "label": "HTTP",    "variant": "emphasis" },
    { "from": "backend",  "to": "db",       "label": "SQL",     "variant": "emphasis" }
  ]
}

```

---

## Processing Pipeline

The Archify JSON IR schema enables a three-stage compilation flow:

1. **Validation** – The compiler checks `schema_version` compatibility and required field presence
2. **Graph construction** – `components`, `connections`, and `boundaries` build the internal representation
3. **Rendering** – SVG generation with interactive HTML output written to `meta.output`

---

## Summary

- The **Archify JSON IR schema** version `1` requires `schema_version`, `diagram_type`, `meta`, `components`, and `connections`
- **Components** need `id`, `type`, `label`, `sublabel`, `pos`, and `size`; optionally use `row`/`col` for grid layouts
- **Boundaries** group components by `kind: "region"` or `"security-group"` with a `wraps` id array
- **Connections** support `label`, `variant` styling, `fromSide`/`toSide` anchors, and `via` waypoints for routing
- **Cards** add sidebar documentation with colored dots, titles, and bullet items
- Reference implementations exist in [[`examples/maka-architecture.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json)](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json) and [[`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json)](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json)

---

## Frequently Asked Questions

### What is the current schema version for Archify JSON IR?

Archify JSON IR uses `schema_version: 1` as of the latest `tt-a1i/archify` release. The compiler validates this field before processing and will reject incompatible future versions until updated.

### Can I use Archify JSON IR for workflow and sequence diagrams?

Yes. The `diagram_type` field accepts `"architecture"`, `"workflow"`, `"dataflow"`, or `"sequence"` values. While the core schema remains identical, the rendering engine applies diagram-specific layouts and styling rules based on this type declaration.

### How do I position components automatically instead of using absolute coordinates?

Use the optional `row` and `col` fields in your component definitions. The [[`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json)](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json) file demonstrates this grid-based placement system, which calculates `pos` values automatically during compilation.

### What connection variants are available for styling edges?

The `variant` field supports `"emphasis"` for bold highlighting, `"dashed"` for informational or optional flows, and `"security"` for trust-boundary crossings. Additional variants may be added in future schema versions based on the styling system in `tt-a1i/archify`.