# How Archify's Validation Pipeline Works: From Render to Deterministic Quality Receipt

> Discover how Archify's validation pipeline ensures syntactically correct and visually trustworthy diagrams with structural SVG checks and geometric analysis.

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

---

**Archify's validation pipeline is a sequential post-render process that guarantees every generated diagram is syntactically correct and visually trustworthy through structural SVG checks and geometric composition analysis.**

Archify's **validation pipeline** ensures architectural diagrams meet strict quality standards before they ever reach users. Implemented across the `tt-a1i/archify` repository, this pipeline automatically runs after every render operation to catch errors that would compromise diagram clarity or correctness.

## Overview of the Validation Pipeline Flow

The pipeline follows a deterministic sequence from HTML generation to JSON receipt output. Understanding this flow is essential for debugging validation failures or extending the system.

### Step 1: Render the Diagram

Every validation starts with rendering. The CLI command `archify render <type> <input.json> <output.html>` triggers this process.

In `bin/archify.mjs`, the `commandRender` function resolves a **type-specific renderer** (such as `render-architecture.mjs`) and executes it. The output is a self-contained HTML file embedding an `<svg>` block with all visual geometry.

```bash

# Render an architecture diagram

archify render architecture examples/web-app.architecture.json web-app.html

```

The `commandRender` function handles renderer path resolution through `rendererPath` and delegates actual SVG generation to the appropriate renderer module.

### Step 2: Execute the Post-Render Checker

Immediately after rendering completes, Archify spawns the **post-render artifact checker** at `scripts/check-render-output.mjs`. This Node.js module reads the generated HTML, extracts the `<svg>` tag, and runs a comprehensive test suite.

```bash

# Run validation explicitly on an existing artifact

archify check web-app.html

```

The checker operates as a standalone script, enabling both integrated and independent validation workflows.

## Structural SVG Validation Checks

The pipeline performs three foundational structural tests before examining geometric relationships.

### single_svg Check

Ensures exactly one `<svg>` element exists in the rendered output. Multiple or missing SVG containers indicate renderer malfunction.

### finite_svg Check

Verifies no `NaN`, `Infinity`, or `undefined` values appear in SVG markup. These values typically signal calculation errors in the rendering pipeline that would produce broken visuals.

### orthogonal_arrows Check

Rejects any arrow segment that is not strictly horizontal or vertical. This architectural constraint prevents diagonal shortcuts that would violate diagram conventions and reduce readability.

## Geometric Composition Checks

After structural validation, the pipeline imports geometry utilities from `renderers/shared/geometry.mjs` to evaluate spatial relationships. These checks use helper functions like `collectArrows`, `collectRelationshipCrossings`, `collectAmbiguousCorridors`, and `collectLabelRouteClearance`.

### Label-Route Clearance

**`label_route_clearance`** verifies relationship labels maintain minimum distance from other routes. Overlapping labels and routes create visual ambiguity that this check prevents.

### Proper Crossings

**`relationship_crossings`** flags unintended intersections between unrelated relationships. The check distinguishes between legitimate crossings (perpendicular path intersections) and problematic overlaps.

### Ambiguous Corridors

**`relationship_corridors`** detects overlapping corridor segments that could be visually ambiguous. These occur when multiple routes occupy the same visual channel without clear separation.

### Container-Border Runs

**`container_border_runs`** ensures routes do not slide along interior frame borders unless explicitly allowed. This prevents cluttered diagrams where routes hug container edges unnaturally.

### Route Rhythm

**`route_rhythm`** enforces limits on bend count, segment stretch, and individual segment length. Excessive bends or elongated segments reduce diagram professionalism and readability.

### Legend Clearance

**`legend_clearance`** checks that no route intrudes into the legend area, preserving the integrity of explanatory content.

## The Composition Receipt Output

After all checks complete, the pipeline aggregates results into a **composition receipt**—a deterministic JSON document describing artifact quality.

The receipt structure includes:

- **`profile`** – `standard` or `showcase` rendering mode
- **`status`** – `pass` or `fail` overall result
- **`summary`** – aggregated error and warning counts
- **`metrics`** – detailed measurements including `properCrossings`, `ambiguousCorridors`, `containerBorderRuns`, `labelRouteClearanceIssues`, and route-budget numbers

```json
{
  "ok": true,
  "file": "web-app.html",
  "checks": [
    { "name": "single_svg", "ok": true },
    { "name": "finite_svg", "ok": true },
    { "name": "orthogonal_arrows", "ok": true }
  ],
  "composition": {
    "schemaVersion": 1,
    "profile": "standard",
    "status": "pass",
    "summary": { "errors": 0, "warnings": 2 },
    "metrics": {
      "properCrossings": 0,
      "ambiguousCorridors": 0,
      "containerBorderRuns": 0,
      "labelRouteClearanceIssues": 2
    }
  }
}

```

In `check-render-output.mjs`, the `checks` array construction spans lines 27–46, while the `composition` object assembly covers lines 28–52.

## Integration Across Archify Commands

The validation pipeline serves multiple high-level workflows through shared logic.

### Gallery Building

`scripts/build-gallery.mjs` renders each example, runs the checker, and stores receipts alongside artifacts. The receipt fields—`checksPassed`, `checkCount`, and `composition`—drive the HTML gallery's quality indicators.

### Delivery Pipeline

The `commandDeliver` function in `bin/archify.mjs` implements a **trust-but-verify** pattern: it renders a candidate, validates it, and only commits the artifact if the receipt reports `ok`. Failed validations leave the previous trusted artifact untouched, ensuring no regression in published diagrams.

### Standalone Validation CLI

The `archify validate <type> <input.json>` command wraps both renderer and checker, exposing receipts directly to users or as JSON via `--json` flag.

## Programmatic Validation Example

For integration into custom workflows, invoke the checker directly through Node.js:

```javascript
const { spawnSync } = require('node:child_process');
const result = spawnSync(process.execPath, [
  'archify/scripts/check-render-output.mjs',
  'web-app.html'
], { encoding: 'utf8', stdio: 'pipe' });

const receipt = JSON.parse(result.stdout);
console.log('Validation status:', receipt.composition.status);
console.log('Warnings:', receipt.composition.summary.warnings);

```

## Key Source Files

| Component | Path |
|-----------|------|
| Post-render artifact checker | `scripts/check-render-output.mjs` |
| Geometry utilities | `renderers/shared/geometry.mjs` |
| CLI entry point | `bin/archify.mjs` |
| Gallery builder | `scripts/build-gallery.mjs` |
| Architecture renderer example | `renderers/architecture/render-architecture.mjs` |

## Summary

- **Archify's validation pipeline** runs automatically after every render operation through `scripts/check-render-output.mjs`
- **Structural checks** (`single_svg`, `finite_svg`, `orthogonal_arrows`) catch malformed SVG before geometric analysis
- **Geometric checks** evaluate label clearance, crossing propriety, corridor ambiguity, container borders, route rhythm, and legend intrusion
- **Composition receipts** provide deterministic, machine-readable quality assessments in JSON format
- **Integration points** include gallery building, delivery gating, and dedicated CLI validation—all sharing identical validation logic

## Frequently Asked Questions

### What happens if a diagram fails validation?

The artifact receives a `"status": "fail"` in its composition receipt, with specific errors detailed in `checks` and `metrics`. In delivery workflows, the previous trusted artifact remains untouched. With `archify check` or `archify validate`, the CLI exits with non-zero status and prints failure details.

### Can I disable specific validation checks?

The pipeline does not support check-level disabling in its current implementation. All structural and geometric checks run unconditionally. Custom profiles (standard vs. showcase) affect rendering parameters but not which checks execute.

### How does the pipeline detect NaN or Infinity values?

The `finite_svg` check scans all numeric attributes in the extracted SVG markup, flagging any `NaN`, `Infinity`, or `undefined` values. This catches cascade failures from upstream geometry calculations before they reach users.

### Where are validation results stored for gallery artifacts?

`scripts/build-gallery.mjs` persists composition receipts as JSON files alongside each HTML artifact. The gallery HTML then loads these receipts to display check status, warning counts, and quality metrics without re-running validation.