# How to Define an Architecture Diagram in Archify's JSON IR Format

> Learn to define architecture diagrams using Archify's JSON IR format. Understand the strict schema requirements for schema_version, diagram_type, meta, and components for accurate representation.

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

---

**Archify represents architecture diagrams as a JSON Intermediate Representation (IR) that validates against a strict schema requiring `schema_version`, `diagram_type`, `meta`, and at least one `component` object.**

Archify is an open-source visualization engine that converts structured JSON into standalone HTML architecture diagrams. To define a diagram, you create a JSON IR file that conforms to the **Architecture Schema** enforced by the AJV validator in the `tt-a1i/archify` repository.

## Core JSON IR Structure

Every architecture diagram must include seven top-level properties. According to [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the document root requires:

- **`schema_version`**: Must be the integer `1` (locked constant)
- **`diagram_type`**: Must be the string `"architecture"`
- **`meta`**: Object containing at least a `title` string
- **`components`**: Array containing at least one component object
- **`layout`**: Optional layout hints (grid mode, origin, gaps)
- **`boundaries`**: Optional array grouping components into regions
- **`connections`**: Optional array of directed edges between components
- **`cards`**: Optional annotation cards displayed alongside the diagram

## Defining Metadata with the meta Object

The `meta` object in [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) demonstrates the required structure. Only `title` is mandatory, but you can configure rendering behavior through additional fields:

- **`subtitle`**: Brief description shown below the title
- **`locale`**: Language code (`"en"` or `"zh-CN"`)
- **`output`**: File path for the generated HTML artifact
- **`repository`**: GitHub repository link with 40-character SHA
- **`views`**: Guided view definitions referencing [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)
- **`viewBox`**: Explicit SVG viewport dimensions

Example from the source:

```json
"meta": {
  "title": "Archify",
  "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML",
  "output": "examples/archify-repo.html"
}

```

## Creating Components

Components are the visual nodes in your diagram. Each entry in the `components` array must include `id`, `type`, and `label` per the schema defined in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json).

### Required Component Fields

- **`id`**: Unique string identifier for referencing in connections
- **`type`**: Enum value limited to `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, or `external`
- **`label`**: Display text for the node

### Optional Positioning and Styling

- **`pos`**: Array `[x, y]` with non-negative coordinates
- **`size`**: Array `[width, height]` with positive integers
- **`row`/`col`**: Grid placement when `layout.mode` is `"grid"`
- **`sublabel`**, **`tag`**, **`brand`**: Additional descriptive text
- **`sources`**: Code reference objects with `path` and line numbers

Example component definition from the reference implementation:

```json
{
  "id": "ir",
  "type": "messagebus",
  "label": "JSON IR",
  "sublabel": "schema_version: 1",
  "pos": [400, 300],
  "size": [140, 60]
}

```

## Grouping Components with Boundaries

Boundaries wrap components into visual regions or security groups. Each boundary object specifies:

- **`kind`**: Either `"region"` or `"security-group"`
- **`label`**: Display name for the boundary
- **`wraps`**: Array of component IDs to include

From [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json):

```json
{
  "kind": "region",
  "label": "archify/ skill package",
  "wraps": ["ir", "schemas", "renderers", "template", "checker"]
}

```

## Establishing Connections

The `connections` array defines directed edges using component IDs. The schema in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) supports sophisticated routing and styling:

- **`from`**/`**to`**: Source and target component IDs (required)
- **`variant`**: Visual style enum (`default`, `emphasis`, `security`, `dashed`)
- **`fromSide`**/`**toSide`**: Anchor attachment (`left`, `right`, `top`, `bottom`)
- **`route`**: Routing algorithm (`auto`, `straight`, `orthogonal-h`, `orthogonal-v`)
- **`via`**: Array of intermediate `[x, y]` points for custom paths
- **`label`**: Text displayed on the edge
- **`labelAt`**, **`labelDx`**, **`labelDy`**, **`labelSegment`**: Fine-tuned label placement
- **`width`**: Line thickness in pixels

Example connection with emphasis styling:

```json
{
  "from": "user",
  "to": "agents",
  "variant": "emphasis"
}

```

## Adding Explanatory Cards

Cards add annotation "sticky notes" to diagrams. Each card requires:

- **`dot`**: Color marker from the palette (`cyan`, `emerald`, `rose`, etc.)
- **`title`**: Heading string
- **`items`**: Array of bullet-point strings

Example card from the demo:

```json
{
  "dot": "emerald",
  "title": "Render path",
  "items": [
    "JSON IR pins schema_version: 1",
    "Five typed renderers: architecture / workflow / sequence / dataflow / lifecycle",
    "template.html owns theme toggle and 4× export"
  ]
}

```

## Validating Your JSON IR

Archify validates documents against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) using **AJV** (Another JSON Schema Validator) as declared in [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json). The validation ensures:

- Required fields are present
- Component types match the enum in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)
- Connection endpoints reference existing component IDs
- Schema version matches the expected constant

## Complete Code Examples

### Minimal Valid Diagram

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "My Simple Architecture"
  },
  "components": [
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Web Frontend",
      "pos": [100, 200],
      "size": [120, 60]
    },
    {
      "id": "backend",
      "type": "backend",
      "label": "API Service",
      "pos": [300, 200],
      "size": [120, 60]
    }
  ],
  "connections": [
    {
      "from": "frontend",
      "to": "backend",
      "variant": "default"
    }
  ]
}

```

### Full-Featured Diagram

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Archify",
    "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML",
    "output": "examples/archify-repo.html"
  },
  "components": [
    { "id": "user", "type": "external", "label": "You", "sublabel": "NL or Mermaid", "pos": [40, 300], "size": [120, 60] },
    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "sublabel": "Claude · Codex · opencode", "pos": [200, 300], "size": [150, 60] },
    { "id": "ir", "type": "messagebus", "label": "JSON IR", "sublabel": "schema_version: 1", "pos": [400, 300], "size": [140, 60] },
    { "id": "renderers", "type": "backend", "label": "Renderers ×5", "sublabel": "layout checks", "pos": [590, 300], "size": [140, 60] },
    { "id": "html", "type": "cloud", "label": "HTML Artifact", "sublabel": "single file", "pos": [1160, 300], "size": [140, 60] }
  ],
  "boundaries": [
    { "kind": "region", "label": "archify/ skill package", "wraps": ["ir", "schemas", "renderers", "template", "checker"] }
  ],
  "connections": [
    { "from": "user", "to": "agents", "variant": "emphasis" },
    { "from": "agents", "to": "ir", "label": "write IR", "variant": "emphasis" },
    { "from": "ir", "to": "renderers", "variant": "emphasis" },
    { "from": "renderers", "to": "template", "variant": "emphasis" },
    { "from": "template", "to": "checker", "variant": "emphasis" },
    { "from": "checker", "to": "html", "label": "deliver", "variant": "emphasis" }
  ],
  "cards": [
    {
      "dot": "emerald",
      "title": "Render path",
      "items": [
        "JSON IR pins schema_version: 1",
        "Five typed renderers: architecture / workflow / sequence / dataflow / lifecycle",
        "template.html owns theme toggle and 4× export"
      ]
    }
  ]
}

```

## Summary

- Archify uses a JSON IR format validated against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) to render architecture diagrams
- Every diagram requires `schema_version: 1`, `diagram_type: "architecture"`, a `meta` object with `title`, and at least one `component`
- Components support positioning via `pos`/`size` or grid-based `row`/`col` placement
- Connections support multiple routing algorithms (`straight`, `orthogonal-h`, `orthogonal-v`, `auto`) and styling variants
- Boundaries group components visually, while cards add explanatory annotations
- The AJV validator in [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json) enforces schema compliance before rendering

## Frequently Asked Questions

### What is the minimum required JSON to create a valid Archify architecture diagram?

The smallest valid diagram requires four top-level properties: `schema_version` set to `1`, `diagram_type` set to `"architecture"`, a `meta` object containing at least a `title` string, and a `components` array with at least one component having `id`, `type`, and `label`. Without these, the AJV validator in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) will reject the input.

### Which component types are available in Archify's JSON IR format?

The `type` field in each component must match an enum defined in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). Valid values are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`. Using any other string will fail schema validation.

### How do I control the routing of connections between components?

Use the `route` property in a connection object to specify the path algorithm. Options include `auto` (default), `straight` (direct line), `orthogonal-h` (horizontal-first Manhattan routing), and `orthogonal-v` (vertical-first Manhattan routing). For custom paths, provide an array of `[x, y]` coordinates in the `via` property to force specific waypoints.

### Can I link a diagram to a specific GitHub repository commit?

Yes. Add a `repository` object to your `meta` section containing `url` (the repository HTTPS path) and `sha` (the 40-character commit hash). This creates a permanent reference between your architecture diagram and the codebase state it represents, as demonstrated in the [`archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify-repo.architecture.json) example.