# Layout JSON Output for Archify Architecture Diagrams: Schema, Grid Mode, and Configuration Guide

> Learn how to layout JSON output for Archify architecture diagrams. Explore grid mode, origin, cols, gapX, gapY, cellW, and cellH settings in this guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: architecture
- Published: 2026-08-10

---

**Archify uses a dedicated `layout` object with a `"grid"` mode to automatically position diagram elements, controlled by parameters like `origin`, `cols`, `gapX`, `gapY`, `cellW`, and `cellH` defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json).**

Archify generates architecture diagrams from structured JSON files, and every diagram supports an optional `layout` section that eliminates manual coordinate calculations. According to the `tt-a1i/archify` source code, this object is formally specified in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) and enables predictable, repeatable placements for complex diagrams such as data pipelines or microservice topologies.

## Layout Object Schema and Required Properties

The `layout` object sits at the top level of any architecture diagram JSON file. The schema mandates a **`mode`** property and accepts several optional geometry parameters that define the grid's structure.

### Core Properties

| Property | Type | Description |
|----------|------|-------------|
| **`mode`** | string (enum) | Must be `"grid"` — currently the only supported layout engine. |
| **`origin`** | `[x, y]` array | Top‑left coordinate of the grid in diagram space. |
| **`cols`** | integer (1–12) | Number of grid columns; defaults to `1` if omitted. |
| **`gapX`** | number ≥ 0 | Horizontal spacing between adjacent cells. |
| **`gapY`** | number ≥ 0 | Vertical spacing between adjacent cells. |
| **`cellW`** | number ≥ 40 | Minimum width of each grid cell. |
| **`cellH`** | number ≥ 24 | Minimum height of each grid cell. |

The constraints on `cellW` and `cellH` ensure that components render with sufficient visual clarity regardless of content density.

## Grid Mode: Automatic Positioning with Row/Col Indices

When `mode` is set to `"grid"`, Archify's renderer calculates component positions automatically. Components reference grid cells using **`row`** and **`col`** indices instead of absolute coordinates.

This system excels for multi‑lane diagrams where logical flow maps cleanly to grid rows. Consider a deployment pipeline with source, build, test, and deploy stages — each stage occupies a column, and each service tier occupies a row.

### Position Override Behavior

A component can still specify a manual **`pos`** array (`[x, y]`) to override grid placement for fine‑grained control. This hybrid approach lets you establish a baseline grid while adjusting critical elements for visual emphasis or connector routing.

## Minimal Layout JSON Output Example

The following snippet demonstrates the smallest valid layout configuration:

```json
{
  "layout": {
    "mode": "grid",
    "origin": [40, 100],
    "cols": 7,
    "gapX": 24,
    "gapY": 48,
    "cellW": 120,
    "cellH": 60
  }
}

```

This defines a 7‑column grid starting at coordinate `(40, 100)`, with 120×60 pixel cells and generous spacing between them.

## Complete Architecture Diagram with Layout

The file [`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json) in the Archify repository provides a full implementation. Here is an annotated excerpt showing how `layout`, `components`, and `connections` interact:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Archify Pipeline",
    "subtitle": "Grid placement demo — row/col instead of manual pos",
    "output": "examples/archify-repo-grid.html"
  },
  "layout": {
    "mode": "grid",
    "origin": [40, 100],
    "cols": 7,
    "gapX": 24,
    "gapY": 48,
    "cellW": 120,
    "cellH": 60
  },
  "components": [
    { "id": "user", "type": "external", "label": "You", "row": 1, "col": 0 },
    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "row": 1, "col": 1 },
    { "id": "skill", "type": "frontend", "label": "SKILL.md", "row": 0, "col": 1 }
  ],
  "connections": [
    { "from": "user", "to": "agents", "variant": "emphasis" },
    { "from": "agents", "to": "skill", "fromSide": "top", "toSide": "bottom" }
  ]
}

```

Notice how components `user`, `agents`, and `skill` use `row` and `col` to target specific grid cells, while connections route between them automatically.

## Source Files and Validation

Archify enforces the layout schema through two key files:

- **[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)** — Contains the complete JSON Schema definition, including type constraints, enum values, and numeric ranges for all layout properties.
- **[`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json)** — A working reference that demonstrates grid layout in a realistic multi‑component diagram.

Any diagram JSON that includes a `layout` object is validated against this schema before rendering, ensuring that malformed configurations fail fast with descriptive errors.

## Summary

- The **layout JSON output** in Archify centers on a `layout` object with `mode: "grid"` as the sole supported engine.
- **Seven properties** control the grid: `mode`, `origin`, `cols` (1–12), `gapX`, `gapY`, `cellW` (≥40), and `cellH` (≥24).
- Components use **`row`** and **`col`** indices for automatic placement, or **`pos`** for manual override.
- The schema lives in **[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)** and is exemplified in **[`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json)**.

## Frequently Asked Questions

### What layout modes does Archify support?

Archify currently supports only the `"grid"` layout mode. The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) file defines this as an enum with a single value, though the schema structure allows for future expansion to additional layout engines.

### Can I mix grid placement with manual positioning?

Yes. Components inside a grid‑mode diagram default to automatic placement via `row` and `col`, but supplying a `pos` array overrides this for that specific component. This hybrid approach enables precise adjustments without abandoning the grid system entirely.

### What happens if I omit the `cols` property in my layout JSON?

The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) schema specifies a default value of `1` for `cols` when omitted. This creates a single‑column vertical stack, which may be useful for simple linear diagrams but typically requires explicit configuration for multi‑column layouts.

### Where can I find the complete schema for layout validation?

The authoritative source is **[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)** in the `tt-a1i/archify` repository. This file defines all layout properties, their types, constraints, and defaults. The file **[`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json)** provides a validated, runnable example for reference.