# Archify JSON IR Structure for Different Diagram Types: Complete Schema Reference

> Explore the Archify JSON IR structure for architecture, workflow, sequence, lifecycle, and dataflow diagrams. Understand the schema reference for each diagram type.

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

---

**Archify represents every diagram as a JSON intermediate representation (IR) that combines common top-level fields—`schema_version`, `diagram_type`, and `meta`—with domain-specific structures defined in separate JSON Schema files for architecture, workflow, sequence, lifecycle, and dataflow diagrams.**

Archify is an open-source diagramming engine that renders production-ready SVG and HTML visuals from declarative JSON input. Mastering the JSON IR structure for different diagram types enables developers to programmatically generate complex architectural blueprints, swim-lane workflows, and UML sequence diagrams. Each schema is strictly validated against official JSON Schema definitions stored in the repository's `archify/schemas/` directory.

## Architecture Diagram IR Structure

The **architecture diagram** schema supports grid-based system architecture visualizations. According to [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the IR requires a grid `layout` mode and defines three primary entity arrays.

**Core fields:**

- **`layout`** – Currently supports only `"mode": "grid"` with `cols`, `cellW`, `cellH`, and spacing parameters.
- **`components`** – Building blocks such as servers or databases with `id`, `type`, `label`, and optional grid coordinates (`row`, `col`) or absolute `pos`.
- **`boundaries`** – Grouping containers with `kind` (region or security-group) and a `wraps` array listing enclosed component IDs.
- **`connections`** – Directed edges between components specifying `from`, `to`, and visual `variant` (emphasis, security, dashed).

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Web Stack" },
  "layout": { "mode": "grid", "cols": 6, "cellW": 120, "cellH": 80 },
  "components": [
    { "id": "users", "type": "frontend", "label": "Users", "row": 0, "col": 0 },
    { "id": "cdn", "type": "cloud", "label": "CDN", "row": 0, "col": 1 },
    { "id": "api", "type": "backend", "label": "API Server", "row": 0, "col": 3 },
    { "id": "db", "type": "database", "label": "PostgreSQL", "row": 0, "col": 4 }
  ],
  "connections": [
    { "from": "users", "to": "cdn", "variant": "emphasis" },
    { "from": "cdn", "to": "api", "variant": "emphasis" }
  ]
}

```

See the full schema at [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) and a production example at [[`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json).

## Workflow Diagram IR Structure

**Workflow diagrams** use a swim-lane (lane-based) layout defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json). The IR separates vertical responsibility lanes from horizontal phase bands.

**Key constructs:**

- **`lanes`** – Vertical swim-lanes (e.g., UI, Agent, Policy) identified by `id` and `label`.
- **`phases`** – Optional horizontal bands grouping columns with `fromCol`, `toCol`, and visual `variant`.
- **`groups`** – Rectangular blocks spanning a specific lane and column range for visual nesting.
- **`nodes`** – Symbols placed at a specific `lane` and `col` coordinate with a defined `type`.
- **`edges`** – Connections featuring a `role` property (main, branch, async, return, error) and `route` hints (auto, drop, outside-right).

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Simple Agent Flow" },
  "lanes": [
    { "id": "ui", "label": "User Interface" },
    { "id": "agent", "label": "Agent Runtime" }
  ],
  "nodes": [
    { "id": "req", "lane": "ui", "col": 0, "type": "frontend", "label": "Request" },
    { "id": "plan", "lane": "agent", "col": 1, "type": "backend", "label": "Planner" },
    { "id": "exec", "lane": "agent", "col": 2, "type": "backend", "label": "Execute" }
  ],
  "edges": [
    { "from": "req", "to": "plan", "role": "main", "variant": "emphasis" },
    { "from": "plan", "to": "exec", "role": "main", "variant": "emphasis" }
  ]
}

```

Reference the schema at [[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) and the multi-step agent example at [[`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json).

## Sequence Diagram IR Structure

The **sequence diagram** IR in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) models temporal interactions between vertical participants using lifelines and horizontal messages.

**Structural elements:**

- **`participants`** – Vertical lifelines categorized by `type` (frontend, backend, database, messagebus, external).
- **`messages`** – Horizontal arrows with `from` and `to` participant IDs, `segment` grouping, and boolean `activation` to render activation bars.
- **`segments`** – Logical phases (e.g., Auth, Cache) that group related messages.
- **`variant`** – Visual styles including `emphasis`, `security`, `dashed`, or `return`.

```json
{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Cache Miss Flow" },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client" },
    { "id": "api", "type": "backend", "label": "API Server" },
    { "id": "redis", "type": "database", "label": "Redis" }
  ],
  "messages": [
    { "id": "m1", "from": "client", "to": "api", "label": "GET /dashboard", "variant": "emphasis", "segment": 0, "activation": true },
    { "id": "m2", "from": "api", "to": "redis", "label": "READ", "variant": "default", "segment": 1, "activation": true },
    { "id": "m3", "from": "redis", "to": "api", "label": "MISS", "variant": "return", "segment": 1 }
  ]
}

```

Validate against [[`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) and study the request-flow example at [[`docs/gallery/sources/cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/cache-miss-request.sequence.json)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/cache-miss-request.sequence.json).

## Lifecycle Diagram IR Structure

**Lifecycle diagrams** visualize state machines with horizontal lanes separating active states from interruptions and terminal exits. The schema is defined in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json).

**Domain-specific fields:**

- **`lanes`** – Horizontal bands such as `main`, `waiting`, `exceptions`, and `terminal`, each with a `variant` (normal or exception).
- **`states`** – Nodes positioned in a specific lane at a `col` index.
- **`transitions`** – Directed edges with `variant` styling (emphasis, security, dashed) and explicit `route` control (auto, straight, orthogonal).

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "lanes": [
    { "id": "main", "label": "Active" },
    { "id": "interrupt", "label": "Interrupt", "variant": "exception" },
    { "id": "terminal", "label": "Exit", "variant": "exception" }
  ],
  "states": [
    { "id": "queued", "lane": "main", "label": "Queued", "col": 0 },
    { "id": "running", "lane": "main", "label": "Running", "col": 1 },
    { "id": "paused", "lane": "interrupt", "label": "Paused", "col": 1 },
    { "id": "cancelled", "lane": "terminal", "label": "Cancelled", "col": 2 }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "variant": "emphasis" },
    { "from": "running", "to": "paused", "variant": "security" },
    { "from": "paused", "to": "running", "variant": "emphasis" }
  ]
}

```

Consult [[`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) and the agent execution example at [[`docs/gallery/sources/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json).

## Data-Flow Diagram IR Structure

**Data-flow diagrams** use a simplified IR defined in [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json). Unlike architecture diagrams, this format omits explicit `layout` hints and grid coordinates; the visual layout is inferred from the preset configuration.

**Minimal structure:**

- **`components`** – Standard entity definitions with `id`, `type`, and `label`.
- **`connections`** – Directed flows with optional text `label` and `variant` styling.

```json
{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Analytics Pipeline" },
  "components": [
    { "id": "web", "type": "frontend", "label": "Web SDK" },
    { "id": "edge", "type": "backend", "label": "Edge API" },
    { "id": "store", "type": "database", "label": "Warehouse" }
  ],
  "connections": [
    { "from": "web", "to": "edge", "variant": "emphasis", "label": "events" },
    { "from": "edge", "to": "store", "variant": "emphasis", "label": "ingest" }
  ]
}

```

Review the full specification at [[`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) and the analytics example at [[`docs/gallery/sources/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json).

## Summary

The Archify JSON IR structure provides a type-safe, schema-validated foundation for five distinct diagram categories:

- **Architecture diagrams** rely on grid-based `layout` with explicit `components`, `boundaries`, and `connections`.
- **Workflow diagrams** organize logic into vertical `lanes`, horizontal `phases`, and semantic `edges` with role-based routing.
- **Sequence diagrams** model time-series interactions through `participants`, `messages`, grouped `segments`, and activation bars.
- **Lifecycle diagrams** separate states into semantic horizontal `lanes` (main, interrupt, terminal) with explicit `transitions`.
- **Data-flow diagrams** offer a simplified component-connection model without manual layout coordinates.

## Frequently Asked Questions

### What fields are common to all Archify JSON IR structures?

Every diagram IR must include `schema_version` (integer), `diagram_type` (string), and `meta` (object). The `meta` object typically contains `title`, optional `subtitle`, `locale`, `viewBox`, and rendering hints like visual preset and quality profile. All schemas also support an optional `cards` object for metadata attachments.

### How does the Workflow diagram IR differ from Architecture diagrams?

Workflow IR uses `lanes` and `nodes` positioned by column index rather than explicit grid coordinates, and it introduces semantic `edges` with `role` properties (main, branch, async, return, error). Architecture diagrams instead use absolute or grid-relative positioning with `row` and `col` fields, and organize components into `boundaries` rather than swim-lanes.

### Can I define custom routing for connections in the JSON IR?

Yes. The workflow, lifecycle, and architecture schemas accept a `route` property on connections or edges. Valid values include `"auto"`, `"straight"`, `"orthogonal"`, `"drop"`, and `"outside-right"`. If omitted, the renderer applies automatic pathfinding based on the diagram type's layout algorithm.

### Where can I find the official JSON Schema definitions for validation?

All schemas reside in the `archify/schemas/` directory: [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json), and [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json). Production-ready examples are located in `archify/examples/` and `docs/gallery/sources/`, providing validated templates for each diagram type.