# How to Specify Component Positions Using Row and Column in Archify

> Learn how to specify component positions in Archify using row and column properties in your JSON definitions. Master grid layouts starting at 0 0.

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

---

**You specify component positions in Archify by adding `row` and `col` properties to your JSON component definitions, using non-negative integers that map to a logical grid starting at `(0, 0)` in the upper-left corner.**

The **tt-a1i/archify** repository renders architecture diagrams from declarative JSON files. To override automatic placement and control exactly where elements appear, you can specify component positions using row and column coordinates that align elements horizontally and vertically on a virtual canvas.

## Understanding the Archify Grid System

Archify arranges diagram elements on a logical grid where coordinates determine spatial relationships. The grid origin `(row: 0, col: 0)` sits at the upper-left corner, with column numbers increasing to the right and row numbers increasing downward.

- **Row** controls vertical positioning. Components sharing the same `row` value align horizontally across the diagram.
- **Column** controls horizontal positioning. Components sharing the same `col` value stack vertically.

When you omit these coordinates, Archify automatically assigns positions based on its internal layout algorithm. Explicitly defining both values gives you precise control over visual ordering.

## Schema Validation and Constraints

The coordinate properties are strictly defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). According to the source schema, both `row` and `col` must be **non-negative integers** (any integer ≥ 0). This validation ensures that coordinates remain within the bounds of the logical grid and prevents positioning errors during rendering.

## Common Layout Patterns

### Horizontal Alignment (Same Row)

Place related services side-by-side by assigning identical `row` values with incrementing `col` values. This creates vertical columns of related components that span horizontally across the diagram.

### Vertical Stacking (Same Column)

Stack architectural layers—such as UI, Backend, and Database tiers—by assigning identical `col` values with increasing `row` values. This visual pattern clearly communicates dependency stacks and data flow direction.

### Complex Grid Layouts

For presentation-ready diagrams or documentation, assign explicit coordinates to every node to create custom layouts that group related concepts spatially, regardless of their order in the JSON array.

## Code Examples

The following examples demonstrate explicit coordinate assignment in Archify definition files.

### Repository Grid Layout

This example from [`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json) places components in a precise grid pattern:

```json
[
  { "id": "skill",   "type": "frontend", "label": "SKILL.md",   "row": 0, "col": 1 },
  { "id": "schemas", "type": "security", "label": "Schema",    "row": 0, "col": 2 },
  { "id": "user",    "type": "external", "label": "You",       "row": 1, "col": 0 },
  { "id": "agents",  "type": "frontend", "label": "Agent Hosts","row": 1, "col": 1 },
  { "id": "ir",      "type": "messagebus","label":"JSON IR",   "row": 1, "col": 2 },
  { "id": "renderers","type":"backend", "label":"Renderers ×5","row": 1, "col": 3 },
  { "id": "template","type":"frontend","label":"template.html","row": 1, "col": 4 },
  { "id": "checker", "type":"security","label":"Output Check","row": 1, "col": 5 },
  { "id": "html",    "type":"cloud",   "label":"HTML",      "row": 1, "col": 6 }
]

```

### Data Flow Diagram

This excerpt from [`examples/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/product-analytics.dataflow.json) uses coordinates to separate frontend, security, and data layers:

```json
[
  { "id": "web",       "type":"frontend",  "label":"Web App",         "row":0, "col":0 },
  { "id": "mobile",    "type":"frontend",  "label":"Mobile",          "row":2, "col":0 },
  { "id": "edge",      "type":"cloud",    "label":"Edge API",        "row":1, "col":0 },
  { "id": "consent",   "type":"security", "label":"Consent Gate",    "row":0, "col":1 },
  { "id": "stream",    "type":"messagebus","label":"Event Stream",   "row":2, "col":1 },
  { "id": "pii",       "type":"security", "label":"PII Vault",       "row":0, "col":2 },
  { "id": "warehouse", "type":"database", "label":"Warehouse",       "row":2, "col":2 },
  { "id": "features",  "type":"database", "label":"Feature Store",   "row":4, "col":2 },
  { "id": "dashboard", "type":"backend",  "label":"Dashboards",      "row":1, "col":2 },
  { "id": "model",     "type":"backend",  "label":"ML Model",        "row":4, "col":4 }
]

```

## How the Renderer Processes Coordinates

The core rendering engine in `archify/renderers/shared/layout-report.mjs` reads the `row` and `col` properties from each component definition to compute final pixel positions. When coordinates are provided, the renderer bypasses automatic layout calculations and maps the integer values directly to grid cells, maintaining consistent spacing between rows and columns regardless of the JSON file's physical structure.

## Summary

- Archify uses a **zero-indexed grid** where `(0, 0)` represents the upper-left corner.
- Add **`row`** and **`col`** properties to component JSON definitions to control placement.
- Both values must be **non-negative integers** as defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json).
- Components with the same **`row`** align horizontally; components with the same **`col`** align vertically.
- The **`layout-report.mjs`** renderer translates these coordinates into final visual positions.

## Frequently Asked Questions

### What happens if I omit the row or column properties?

If you omit coordinates, Archify automatically assigns the next available grid slot based on its internal layout algorithm. The component will render, but you lose explicit control over its position relative to other elements.

### Can I use negative numbers for row or column values?

No. The JSON schema in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) explicitly defines both properties as non-negative integers. Negative values will fail schema validation and prevent the diagram from rendering.

### How do I align multiple components horizontally?

Assign the same `row` value to each component while incrementing the `col` value for each subsequent element. This places them side-by-side in the same horizontal line.

### Which file handles the coordinate processing during rendering?

The `archify/renderers/shared/layout-report.mjs` module contains the layout engine that processes `row` and `col` values, converting logical grid coordinates into the final visual positions displayed in your architecture diagrams.