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

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.

# 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.

# 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

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

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.

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