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

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:

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:

// 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}