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

> Archify validates diagram composition by scanning HTML, computing structural metrics, and comparing them to thresholds for pass or fail status. Learn how Archify checks your diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-29

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
$ 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:

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

```html
<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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md). These values determine the maximum acceptable counts for micro segments, improper crossings, and other quality indicators.