How to Use the Archify Inspect Command for Layout Diagnostics

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 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:

# 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 (lines 70-73): Contains the official usage syntax and documents the Architecture-only limitation.
• 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: 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.

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 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, 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 at lines 21-25, which explains when developers must use inspect to verify that diagrams accurately reflect actual codebase structure.

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