How to Specify Component Positions Using Row and Column in Archify

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. 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 places components in a precise grid pattern:

[
  { "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 uses coordinates to separate frontend, security, and data layers:

[
  { "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.
• 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 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.

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