# Grid Layout System for Archify Architecture Diagrams: JSON Configuration and Position Resolution

> Explore Archify's grid layout system for architecture diagrams. Learn how it maps components to fixed cells using row/column indices and calculates pixel coordinates via deterministic arithmetic.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-15

---

**Archify’s grid layout system maps architecture components to fixed cell positions using row and column indices, calculating pixel coordinates through deterministic arithmetic defined in `grid.mjs` while allowing absolute coordinate overrides.**

Archify is an open-source diagramming tool that renders architecture diagrams from JSON-encoded intermediate representations (IR). When you set `"mode": "grid"` in your diagram’s top-level `layout` object, the **grid layout system for Archify architecture diagrams** activates deterministic placement based on configurable cell parameters rather than free-hand coordinates.

## How the Grid Layout System Works in Archify

The grid layout processes your architecture IR through three distinct phases: parameter merging, position resolution, and validation. This pipeline ensures reproducible diagrams while maintaining strict constraints on component placement.

### Default Grid Parameters in grid.mjs

When your diagram does not specify custom grid values, Archify imports preset defaults from `archify/renderers/architecture/grid.mjs`:

```js
{
  mode: 'grid',
  origin: [40, 80],
  cols:   4,
  gapX:   30,
  gapY:   40,
  cellW:  130,
  cellH:  64
}

```

These defaults establish the coordinate system origin at `(40, 80)`, define a four-column grid, and set uniform gaps between cells. Every grid diagram starts from this baseline unless explicitly overridden.

### Merging User Configuration

The `gridLayout(arch)` function (lines 13–17 in `grid.mjs`) performs a shallow merge between the preset defaults and any user-supplied `layout` properties. If `layout.mode` is not `"grid"`, the function returns `null`, signaling the renderer to use free-form positioning instead.

### Position Resolution and Validation

Each component in your architecture can specify placement via either `row`/`col` indices or absolute `[x, y]` coordinates. The `resolveComponentPos(component, grid)` function (lines 27–31) translates grid indices to pixel coordinates using the formula:

```

x = originX + col * (cellW + gapX)
y = originY + row * (cellH + gapY)

```

Before rendering, `validateGridPlacement` (lines 33–61) enforces four critical constraints:

- Every component must have either a `pos` array or valid `row`/`col` values
- Row and column indices must be non-negative integers
- Column values cannot exceed the `grid.cols` limit
- No two components may occupy the identical cell

Validation errors accumulate in a `problems` array that the CLI surfaces to the user.

## Positioning Components Using Row and Column Indices

To place components using the grid system, assign `row` and `col` properties in your JSON definition. This example from [`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json) demonstrates a multi-column layout:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "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": "Agents", "row": 1, "col": 1 },
    { "id": "skill",  "type": "frontend", "label": "SKILL",  "row": 0, "col": 1 }
  ]
}

```

After processing, the CLI generates an SVG where the background shows the grid pattern and components align to their specified cells (as verified in `archify/test/cli.test.mjs`, lines 161–167).

### Absolute Position Overrides

You can override grid calculations for individual components by providing a `pos` array. When `resolveComponentPos` detects a `pos` property, it returns those coordinates directly, bypassing the row/cell arithmetic:

```json
{
  "components": [
    {
      "id": "skill",
      "type": "frontend",
      "label": "SKILL",
      "row": 0,
      "col": 1,
      "pos": [300, 180]
    }
  ]
}

```

This technique allows fine-tuned adjustments without abandoning the grid system entirely.

## Configuring the Grid in Your Architecture Diagram

The `layout` object in your IR supports six grid-specific properties:

- **origin**: `[x, y]` array defining the top-left coordinate of the grid
- **cols**: Integer specifying the maximum number of columns
- **cellW**: Width of each grid cell in pixels
- **cellH**: Height of each grid cell in pixels
- **gapX**: Horizontal spacing between columns
- **gapY**: Vertical spacing between rows

When the diagram reaches the final rendering stage in `render-architecture.mjs` (line 220), the top-level `layout` object is stored as:

```js
layout: grid ? { mode: 'grid', ...grid } : { mode: 'free' }

```

This structure signals downstream renderers to apply grid-based clipping and background pattern generation.

## Programmatic Access to Grid Calculations

You can import the grid utilities directly from `grid.mjs` to preview positions or build custom tooling:

```js
import { gridLayout, resolveComponentPos } from './archify/renderers/architecture/grid.mjs';
import arch from './my-diagram.architecture.json' assert { type: 'json' };

const grid = gridLayout(arch);
if (grid) {
  arch.components.forEach(comp => {
    const [x, y] = resolveComponentPos(comp, grid);
    console.log(`${comp.id}: (${x}, ${y})`);
  });
}

```

This script outputs the exact pixel coordinates that Archify will use during SVG generation, enabling you to verify placement before rendering.

## Summary

- Archify activates grid layout when `layout.mode` is set to `"grid"` in your architecture diagram JSON.
- Default parameters in `grid.mjs` provide a 4-column baseline with predefined cell dimensions and gaps.
- The `gridLayout` function merges user settings with defaults, while `resolveComponentPos` converts `row`/`col` indices to pixel coordinates using deterministic arithmetic.
- `validateGridPlacement` enforces non-negative indices, column limits, and prevents duplicate cell occupancy before rendering occurs.
- Components can override grid calculations by specifying a `pos` array for fine-tuned positioning.
- The final layout object stored in `render-architecture.mjs` (line 220) informs downstream renderers to generate grid backgrounds and cell-aligned SVG elements.

## Frequently Asked Questions

### How do I enable grid layout in Archify architecture diagrams?

Set `"mode": "grid"` inside the top-level `layout` object of your JSON intermediate representation. You can optionally provide `origin`, `cols`, `cellW`, `cellH`, `gapX`, and `gapY` values to customize the grid; otherwise, Archify uses the defaults defined in `grid.mjs`.

### Can I mix grid-based positioning with absolute coordinates?

Yes. The `resolveComponentPos` function checks for a `pos` property before calculating grid coordinates. If `pos` exists as an `[x, y]` array, those values override the computed grid position, allowing precise adjustments for individual components while maintaining the grid structure for others.

### What are the default grid parameters in Archify?

The fallback configuration in `archify/renderers/architecture/grid.mjs` sets `origin` to `[40, 80]`, `cols` to `4`, `gapX` to `30`, `gapY` to `40`, `cellW` to `130`, and `cellH` to `64`. These values determine a compact, four-column layout unless your JSON explicitly overrides them.

### How does Archify validate grid placement?

The `validateGridPlacement` function (lines 33–61 in `grid.mjs`) verifies that all components have valid positioning data, ensures `row` and `col` values are non-negative integers within the column limit, and detects duplicate cell occupancy. Any violations are collected in a `problems` array that the CLI reports before rendering fails.