# Archify Grid Placement: How the Architecture Renderer Positions Components Using Row/Col Mode

> Discover how Archify's architecture renderer places components using row/col mode. Learn about deterministic math, explicit positioning, and overlap prevention in grid.mjs.

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

---

**Archify's architecture renderer handles grid placement by translating row and column indices into pixel coordinates using deterministic math implemented in `grid.mjs`, where explicit `pos` arrays override grid calculations and validation prevents overlapping components.**

Archify provides a deterministic **grid placement** system that allows developers to position architecture components using logical row and column indices rather than absolute pixel coordinates. This mode is implemented in the architecture renderer through pure functions that convert grid coordinates to screen positions, prioritizing explicit positioning when provided while validating placements to prevent layout errors.

## Core Grid Functions in `grid.mjs`

The grid placement logic resides in `archify/renderers/architecture/grid.mjs` and consists of three primary functions that handle configuration resolution, coordinate calculation, and validation.

### `gridLayout`: Merging Configuration

The `gridLayout` function reads user-supplied layout definitions and merges them with default grid settings. Located at lines 13-16 of `grid.mjs`, this function ensures that partial configurations inherit sensible defaults from `DEFAULT_GRID` before any positioning calculations occur.

### `resolveComponentPos`: Coordinate Calculation

The `resolveComponentPos` function computes final `[x, y]` pixel positions for components. Implemented at lines 19-31, it first checks for an explicit `pos` array using `Array.isArray(component.pos)`. If present, that value is returned verbatim; otherwise, it translates `row` and `col` properties into screen coordinates using the grid's origin, cell dimensions, and gaps.

### `validateGridPlacement`: Sanity Checks

Running at lines 33-62, `validateGridPlacement` executes when `layout.mode === "grid"`. It verifies that each component has either a `pos` array or valid `row/col` values, ensures rows and columns are non-negative integers, checks that columns stay within `layout.cols`, and prevents duplicate cell assignments by collecting problems in a `problems` array.

## Row/Col to Pixel Conversion Logic

When `resolveComponentPos` processes grid-based placement, it applies deterministic math to convert logical grid positions to pixel coordinates. The conversion formula implemented at lines 27-30 calculates:

```javascript
const [ox, oy] = grid.origin;
const stepX = grid.cellW + grid.gapX;
const stepY = grid.cellH + grid.gapY;
const x = ox + component.col * stepX;
const y = oy + component.row * stepY;

```

This calculation uses the grid origin as the starting point, then multiplies the column index by the combined cell width and horizontal gap, and the row index by the combined cell height and vertical gap.

## Default Grid Configuration

If the architecture JSON omits a custom layout, Archify falls back to `DEFAULT_GRID` with the following properties:

- **Origin**: [40, 80]
- **Columns**: 4
- **Horizontal gap**: 30 pixels
- **Vertical gap**: 40 pixels
- **Cell width**: 130 pixels
- **Cell height**: 64 pixels

These defaults ensure immediate usability while allowing complete customization through the layout configuration object.

## Practical Implementation Example

The following example demonstrates defining an architecture with grid placement, resolving positions, and validating the layout:

```javascript
// Define architecture with grid placement
const arch = {
  layout: {
    mode: 'grid',
    origin: [40, 80],
    cols: 3,
    gapX: 20,
    gapY: 30,
    cellW: 120,
    cellH: 60,
  },
  components: [
    { id: 'api', row: 0, col: 0 },
    { id: 'frontend', row: 1, col: 2 },
    { id: 'db', pos: [300, 200] }  // Explicit position overrides grid
  ],
};

// Resolve positions
import { gridLayout, resolveComponentPos } from './grid.mjs';

const grid = gridLayout(arch);
arch.components.forEach(c => {
  const [x, y] = resolveComponentPos(c, grid);
  console.log(`${c.id} → (${x}, ${y})`);
});
/* Output:
   api → (40, 80)
   frontend → (300, 170)  // 40 + 2*(120+20), 80 + 1*(60+30)
   db → (300, 200)        // explicit pos bypasses row/col math
*/

// Validate before rendering
import { validateGridPlacement } from './grid.mjs';

const problems = [];
validateGridPlacement(arch, grid, problems);
if (problems.length) {
  console.error('Grid placement errors:', problems);
}

```

During rendering, `render-architecture.mjs` calls `gridLayout` to obtain the active configuration, then iterates over components invoking `resolveComponentPos` to obtain pixel coordinates for drawing. The renderer does not perform automatic layout; placement is purely deterministic based on the grid definition.

## Summary

- **Grid placement** in Archify uses three core functions in `grid.mjs`: `gridLayout` for configuration merging, `resolveComponentPos` for coordinate math, and `validateGridPlacement` for error checking.
- Explicit `pos` arrays take precedence over `row`/`col` values when both are present, as detected by `Array.isArray(component.pos)`.
- The conversion formula combines origin coordinates with cell dimensions and gaps to produce deterministic pixel positions.
- Validation ensures non-negative integers, column bounds checking against `layout.cols`, and prevents overlapping component placements.
- Default grid settings in `DEFAULT_GRID` provide immediate usability while supporting full customization.

## Frequently Asked Questions

### How does explicit `pos` override row/col in Archify?

When a component defines `pos: [x, y]`, the `resolveComponentPos` function detects this via `Array.isArray(component.pos)` and returns the explicit coordinates immediately at lines 19-31. This bypasses all row/column calculations, allowing precise pixel positioning for specific components while maintaining grid placement for others.

### What validation does Archify perform for grid placement?

The `validateGridPlacement` function at lines 33-62 checks that the layout mode is "grid", verifies each component has either a `pos` array or valid `row/col` integers, ensures row and column values are non-negative, validates that column indices remain within `layout.cols`, and detects duplicate cell assignments to prevent overlapping components.

### Where is the grid placement logic implemented in Archify?

The core logic resides in `archify/renderers/architecture/grid.mjs`, specifically lines 13-16 for configuration merging, lines 19-31 for position resolution, and lines 33-62 for validation. The consumer `archify/renderers/architecture/render-architecture.mjs` integrates these utilities during the rendering pipeline to produce the final output.

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

If unspecified, Archify uses `DEFAULT_GRID` with origin [40, 80], 4 columns, horizontal gap of 30 pixels, vertical gap of 40 pixels, cell width of 130 pixels, and cell height of 64 pixels. These values are defined in `grid.mjs` and merged with user configurations via `gridLayout`.