How Archify Performs Composition Checks on Diagrams: HTML Scanning and Metric Validation

Archify validates diagram composition by scanning rendered HTML markup for data-composition-* attributes, computing structural metrics like edge crossings and border segments, and comparing these values against profile-specific thresholds to generate a pass or fail status in the validation receipt.

Archify, an open-source architecture visualization tool maintained in the tt-a1i/archify repository, automatically enforces visual quality standards through automated composition checks during the preview and build processes. After rendering a diagram to HTML, the validation pipeline analyzes the generated markup to detect structural issues such as cramped layouts or improper edge crossings. These checks ensure that architecture diagrams remain readable and professionally structured before publication.

Scanning HTML Structure for Composition Data

During the preview process, Archify renders the diagram to HTML and injects special data-composition-* attributes into the markup. These attributes describe structural frames—including regions, lanes, and security groups—and trace the paths of edges throughout the diagram.

The validator parses this annotated markup to build an internal representation of the diagram's visual topology. According to the source code in archify/bin/preview.mjs, this extraction step captures the geometric relationships between containers and connections, preparing the data for quantitative analysis.

Calculating Composition Metrics

Once the structural data is extracted, Archify computes a set of composition metrics that quantify the diagram's visual quality:

• properCrossings — The number of correctly ordered edge crossings, indicating well-organized path intersections.
• containerBorderRuns — The count of continuous border segments in containers, measuring structural coherence.
• microSegmentCount — The total count of tiny line segments, which can signal excessive fragmentation.
• shortInteriorSegmentCount — The number of short interior segments that may indicate cramped or cluttered layout zones.

These metrics are aggregated into a composition profile—such as showcase or standard—that defines the expected quality level for the diagram.

Validation Logic and Status Determination

The validator compares the computed metrics against built-in thresholds defined for the selected composition profile. If all metrics satisfy the profile’s rules, the system sets compositionStatus to pass; otherwise, it reports a failure.

This validation result is packaged into a receipt object that Archify returns from commands like archify preview. The receipt structure includes the profile name, status, and detailed metrics, as defined in archify/references/delivery-contract.md.

Retrieving Composition Results

CLI Output

During a normal run, Archify prints a human-readable summary that includes the composition status. In archify/bin/archify.mjs at line 1025, the tool logs the validation outcome:

$ archify preview diagram.json

# … other output …

artifact checks; composition showcase: pass; sha256 a1b2c3d4e5…

Programmatic Access via Receipt

For automated workflows, you can capture the JSON receipt to inspect composition data programmatically:

import { execSync } from 'child_process';

// Run preview and capture JSON receipt
const receipt = JSON.parse(
  execSync('archify preview diagram.json --json', { encoding: 'utf8' })
);

console.log('Composition profile:', receipt.validation.compositionProfile);
console.log('Composition status:', receipt.validation.compositionStatus);

The receipt object containing compositionProfile and compositionStatus is generated in archify/bin/preview.mjs and validated in archify/test/preview.test.mjs, which asserts that successful previews return compositionProfile: 'showcase' and compositionStatus: 'pass'.

Rendering Metrics in the Gallery View

The gallery interface displays computed composition metrics alongside each diagram. In scripts/build-gallery.mjs at line 235, the rendering logic generates HTML that exposes the underlying metrics via tooltip attributes:

<div class="receipt-cell">
  <span class="receipt-label">Composition</span>
  <span class="receipt-value ok"
        title="3 crossings · 2 border runs · 45 micro segments · 7 cramped turns">
    SHOWCASE · PASS
  </span>
</div>

This visualization allows users to inspect specific metric values—such as the count of micro segments or border runs—without parsing the JSON receipt manually.

Core Implementation Files

The composition validation system spans several key files in the tt-a1i/archify repository:

• archify/bin/preview.mjs — Executes the preview command, extracts composition data from HTML, and assembles the receipt object containing compositionProfile and compositionStatus.
• archify/bin/archify.mjs — Logs the final validation summary to the CLI, including the composition profile and pass-fail status (line 1025).
• scripts/build-gallery.mjs — Generates the gallery UI and renders detailed composition metrics with tooltips (line 235).
• archify/test/preview.test.mjs — Unit tests that verify the receipt contains valid composition fields and statuses.
• archify/references/delivery-contract.md — Defines the JSON schema for the validation payload, including all composition-related fields.

Summary

• Archify performs composition checks by scanning rendered HTML for data-composition-* attributes that describe frames and edges.
• Four key metrics—properCrossings, containerBorderRuns, microSegmentCount, and shortInteriorSegmentCount—determine visual quality.
• Composition profiles (showcase, standard) define acceptance thresholds; diagrams receive a compositionStatus of pass or fail based on metric compliance.
• Validation results are accessible via CLI output, JSON receipt objects, and visual gallery tooltips.
• Source implementation resides in archify/bin/preview.mjs, archify/bin/archify.mjs, and scripts/build-gallery.mjs.

Frequently Asked Questions

What triggers a composition check failure in Archify?

A failure occurs when any computed metric exceeds the tolerance thresholds defined for the active composition profile. For example, a high shortInteriorSegmentCount or excessive microSegmentCount will cause compositionStatus to report fail if they violate the showcase or standard profile limits.

How do I change the composition profile from showcase to standard?

You specify the desired profile when invoking the preview or build command. The validator in archify/bin/preview.mjs accepts profile configuration and applies the corresponding thresholds during metric comparison. Check the command-line help or archify/references/delivery-contract.md for the exact flag syntax.

Can I access raw composition metrics without running the full preview?

No, Archify computes composition metrics during the rendering phase because it requires the HTML markup to analyze structural attributes. The metrics are only available after the diagram is rendered and validated, typically through the --json flag on the preview command or the gallery interface.

Where are the composition threshold values defined?

Threshold values for each profile are defined in the validation configuration, referenced in archify/bin/preview.mjs and documented in archify/references/delivery-contract.md. These values determine the maximum acceptable counts for micro segments, improper crossings, and other quality indicators.

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