What Is Composition Checking in Archify? Layout Validation for Architecture Diagrams

Composition checking in Archify is a validation step that analyzes the geometric layout of architecture diagrams to detect visual issues like edge crossings and clutter, assigning a "pass" or "fail" status based on configurable thresholds.

The tt-a1i/archify repository includes a composition validator that automatically inspects every generated diagram. This process ensures that architecture visualizations maintain readability standards by checking for geometric anti-patterns before they reach production. Composition checking evaluates spatial relationships between frames and edges, returning a structured report within the artifact receipt.

How Composition Checking Works

When Archify generates a diagram, the composition validator evaluates the spatial arrangement of elements. It calculates specific geometric metrics to quantify visual clarity and stores the results in a validation.composition object.

Core Composition Metrics

The validator tracks six key indicators of diagram quality:

• properCrossings: Counts edge-to-edge intersections that should be avoided for readability.
• containerBorderRuns: Measures how many times a frame's border is broken by interior elements.
• microSegmentCount: Tallies short line segments that cause visual clutter.
• shortInteriorSegmentCount: Counts interior line segments that are unusually short, often indicating cramped turns.
• compositionProfile: A named profile (e.g., "showcase") that groups threshold settings for the above metrics.
• compositionStatus: The final verdict, returning "pass" if all metrics are within acceptable thresholds, otherwise "fail".

Validation Profiles

Each diagram is evaluated against a specific composition profile that defines acceptable thresholds. The "showcase" profile represents a strict preset designed for publication-ready diagrams, ensuring minimal crossings and clean geometry.

Running Composition Checks in the Archify CLI

The validator executes automatically during several CLI workflows, printing human-readable summaries or structured JSON receipts.

Preview Command Validation

To validate a single diagram and view the composition status:

npx archify preview path/to/architecture.json

A successful check produces output like:

✔ 1/1 artifact checks; composition SHOWCASE: PASS

If metrics exceed thresholds, the status changes to FAIL:

✖ 1/1 artifact checks; composition SHOWCASE: FAIL

Extracting Detailed Metrics

To inspect the raw composition data programmatically, use the --json flag:

npx archify preview --json path/to/architecture.json | jq '.validation.composition'

This outputs the validation object:

{
  "properCrossings": 0,
  "containerBorderRuns": 1,
  "microSegmentCount": 3,
  "shortInteriorSegmentCount": 0,
  "profile": "showcase",
  "status": "pass"
}

Gallery Validation

During bulk operations, archify build-gallery renders a gallery of artifacts. As implemented in scripts/build-gallery.mjs (lines 225-320), this command displays composition status badges for each diagram, enabling quick identification of layout failures across multiple files.

Source Code Implementation

The composition checking system spans the CLI entry point, receipt generation, and test suite.

CLI Receipt Processing

In archify/bin/archify.mjs at line 1022, the CLI extracts compositionStatus from the artifact receipt. It formats the human-readable summary displayed in terminal output, parsing the validation.composition object to render the pass/fail indicators.

Gallery Badge Generation

The gallery builder in scripts/build-gallery.mjs processes composition data to generate visual badges. Between lines 225 and 320, the script reads each artifact's validation metadata and renders composition profiles alongside pass/fail status indicators, making diagnostic information accessible in bulk renders.

Test Coverage

The validation logic is enforced by tests in archify/test/preview.test.mjs at line 232. The test suite asserts that successful preview operations return compositionStatus: 'pass', ensuring that regressions in layout validation trigger build failures.

Receipt Generation

The underlying geometric calculations occur during the preview phase. The archify/bin/preview.mjs module generates the artifact receipt, populating the validation.composition object with calculated metrics before Archify finalizes the output file.

Summary

• Composition checking in Archify validates diagram geometry against readability standards.
• Six metrics—including proper crossings, border runs, and micro-segments—determine visual quality.
• The validator returns both a binary status and detailed JSON reports via the artifact receipt.
• Checks run automatically during archify preview and archify build-gallery operations.
• Implementation spans archify.mjs, build-gallery.mjs, preview.mjs, and associated test files.

Frequently Asked Questions

What triggers a composition check to fail?

A composition check fails when any metric exceeds its threshold for the active profile. For example, excessive proper crossings or a high micro-segment count will set compositionStatus to "fail" and expose the offending metrics in the validation receipt, allowing developers to identify specific layout problems.

How do I view detailed composition metrics?

Run npx archify preview --json followed by your diagram path and pipe the output through a JSON processor like jq to extract the .validation.composition object. This reveals exact counts for crossings, border runs, and segment lengths associated with your architecture.

Is composition checking mandatory in Archify?

Based on the source analysis, composition checking appears to be a mandatory quality gate. The test suite in archify/test/preview.test.mjs explicitly asserts that previews must return compositionStatus: 'pass', and the CLI displays validation results for every artifact without documented opt-out flags.

What is the "showcase" composition profile?

The "showcase" profile is a strict validation preset designed for publication-ready diagrams. As shown in the CLI output and JSON receipts, this profile enforces tight thresholds on geometric metrics to ensure diagrams meet high readability standards suitable for documentation and presentations.

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