# How to Use the Archify Inspect Command for Layout Diagnostics

> Master Archify inspect for layout diagnostics. Get JSON output of diagram layout, including coordinates & edge routing, to programmatically detect collisions and overlaps.

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

---

**The `inspect` command outputs a deterministic JSON representation of your Architecture diagram's layout, including exact coordinates and edge routing, enabling programmatic diagnosis of geometric collisions and overlaps.**

The `inspect` command in the **tt-a1i/archify** repository is a low-level diagnostic tool designed for developers who need to debug geometric issues in Architecture diagrams. Unlike the standard rendering pipeline that produces visual artifacts, this command exposes the machine-readable layout data generated by Archify's deterministic layout engine, allowing you to validate node placements and edge routes without opening a browser.

## What the Inspect Command Does

When you run `inspect`, Archify parses the JSON IR (Intermediate Representation), executes the layout engine defined in the CLI entry point, and emits a JSON object containing precise geometric data. According to the implementation in `bin/archify.mjs`, this output includes:

- Exact `x` and `y` coordinates for every node
- View-box dimensions for the diagram canvas
- Computed routing paths for all relationships

This allows you to identify misplaced nodes, overlapping edges, or collision reports from the validator—such as when "the `auth` node collides with the `db` node" or "the `api → cache` edge crosses another edge."

## Current Limitations

The command is deliberately restricted to **Architecture** diagram types only. As documented in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) at lines 70-73, other diagram types including Workflow, Sequence, Data-flow, and Lifecycle do not yet expose a stable layout schema for inspection. For these types, you must render the diagram in a browser and use the built-in inspector UI.

## Step-by-Step Diagnostic Workflow

### 1. Validate the Diagram First

Before inspecting layout geometry, ensure your diagram passes all schema and semantic checks. This eliminates validation errors that could affect layout calculation and ensures the coordinates reflect a valid architecture state.

### 2. Generate the Layout JSON

Run the `inspect` subcommand against your Architecture diagram source file. The CLI entry point in `bin/archify.mjs` handles argument parsing and invokes the deterministic layout engine, emitting the layout JSON to stdout.

### 3. Parse and Diagnose

Extract the `layout` field from the output, which contains an array of node objects (`id`, `x`, `y`, `width`, `height`) and an array of relationship objects (`source`, `target`, `path`). Use this data to verify specific coordinates or feed into visual diff tools to compare versions.

## Practical Usage Examples

The following examples demonstrate the complete diagnostic workflow using the Archify CLI:

```bash

# 1️⃣ Validate the Architecture diagram first (optional but recommended)

node bin/archify.mjs validate architecture examples/web-app.architecture.json \
  --quality showcase --json

# 2️⃣ Run the layout inspector

node bin/archify.mjs inspect architecture examples/web-app.architecture.json \
  > layout.json

# 3️⃣ Inspect the JSON (example using `jq` for readability)

jq .layout layout.json

# 4️⃣ Find a specific node (e.g., the “auth” service) and print its coordinates

jq '.nodes[] | select(.id=="auth") | {x, y, width, height}' layout.json

# 5️⃣ Compare two layouts – previous version vs. updated version

node bin/archify.mjs inspect architecture old-version.json > old.json
node bin/archify.mjs inspect architecture new-version.json > new.json
jq -s '.[0].nodes as $a | .[1].nodes as $b | $a[] | select(.id as $id | $b[]?.id == $id) |
  {id, oldX: .x, newX: ($b[] | select(.id==$id) | .x)}' old.json new.json

```

These commands produce deterministic JSON output suitable for custom scripts, unit-test snapshots, or automated regression detection.

## Source Code References

The implementation and documentation for the `inspect` command are distributed across several key files in the repository:

- **`bin/archify.mjs`**: The CLI entry point that parses the `inspect` sub-command and executes the layout engine.
- **[`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md)** (lines 70-73): Contains the official usage syntax and documents the Architecture-only limitation.
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** (lines 21-25): Defines the high-level skill contract explaining when repository evidence requires layout inspection to ensure diagrams reflect real code structure.
- **[`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md)**: Describes the distinction between programmatic layout inspection and browser-based visual validation of final HTML artifacts.

## Summary

- The `inspect` command exports deterministic JSON layout data for Architecture diagrams only.
- Use it to diagnose geometric collisions, edge crossings, and coordinate drifts programmatically.
- Always validate diagrams before inspection to ensure accurate geometric calculation.
- The output includes node coordinates (`x`, `y`, `width`, `height`) and relationship routing paths.
- Implementation resides in `bin/archify.mjs` with usage documented in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md).

## Frequently Asked Questions

### Why is the inspect command limited to Architecture diagrams?

Other diagram types (Workflow, Sequence, Data-flow, Lifecycle) do not yet expose a stable layout schema for programmatic inspection. As noted in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) at line 73, these types require using the browser-based inspector UI instead because their layout engines lack the deterministic JSON contract that `inspect` relies on.

### How does inspect differ from browser-based visual checking?

The `inspect` command outputs raw JSON layout data for programmatic analysis before rendering, while visual checking involves validating the final HTML artifact in a browser. According to [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), visual validation occurs against the rendered runtime output, whereas `inspect` operates on the layout engine's geometric calculations.

### Can I use inspect output for automated snapshot testing?

Yes. Because the output is pure JSON containing deterministic coordinates, you can capture layout snapshots and compare them in CI/CD pipelines to detect unintended geometric changes or regressions in node positioning and edge routing.

### Where is the inspect command implemented in the source code?

The CLI argument parsing and command routing live in `bin/archify.mjs`. The skill contract mentioning repository evidence inspection is located in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) at lines 21-25, which explains when developers must use `inspect` to verify that diagrams accurately reflect actual codebase structure.