# How Archify's Validation System Works: Artifact Checks for Showcase Quality

> Discover how Archify's validation system ensures showcase quality. Learn about its two-stage artifact checks including JSON schema validation and post-render geometric checks.

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

---

**Archify validates diagrams in two stages—JSON schema validation with AJV followed by post-render geometric checks on the SVG output—to ensure showcase-quality artifacts meet strict visual standards.**

The `tt-a1i/archify` repository implements a rigorous **validation system** that gates diagram quality through automated schema and geometric verification. Understanding how these **artifact checks** enforce **showcase quality** ensures your architecture diagrams meet production standards before deployment.

## Two-Stage Validation Architecture

Archify employs a fail-closed validation pipeline that verifies diagrams both before and after rendering.

### Stage 1: JSON Schema Validation with AJV

The first layer validates the JSON "IR" (Intermediate Representation) against a JSON Schema using **AJV**. This structural validation catches malformed data before it reaches the renderers. In `archify/bin/archify.mjs`, the CLI loads the input JSON and runs AJV validation to guarantee that only well-formed data proceeds to the rendering stage.

### Stage 2: Post-Render SVG Validation

After the renderer produces an HTML file containing an `<svg>` diagram, a **zero-dependency checker** located at `archify/scripts/check-render-output.mjs` parses the SVG and executes a suite of geometric checks. This stage ensures the visual output meets composition standards and drives the **showcase-quality** gating mechanism.

## The Validation Flow

The complete validation pipeline follows four distinct steps:

1. **JSON → Renderer**: The CLI (`archify/bin/archify.mjs`) loads the JSON, runs AJV validation, then calls a type-specific renderer (`render-<type>.mjs` in `archify/renderers/*/render-*.mjs`).

2. **Render → HTML/SVG**: The renderer writes an HTML file containing a single `<svg>` with attributes `data-quality-profile` (`standard` or `showcase`) and `data-quality-gates` (`advisory` or `enforced`).

3. **Post-Render Check**: `scripts/check-render-output.mjs` reads the HTML, extracts the SVG, and runs the artifact check battery. The result is a JSON receipt printed to stdout with an exit code (`0` indicates pass).

4. **Gallery Manifest**: `scripts/build-gallery.mjs` invokes the renderer, then the checker, recording receipt data including checks passed, composition status, SHA-256, and file size into [`gallery/manifest.json`](https://github.com/tt-a1i/archify/blob/main/gallery/manifest.json).

## Core Artifact Checks for Showcase Quality

The checker defines named geometric checks in `archify/scripts/check-render-output.mjs`. Each check produces a boolean `ok` status and optional diagnostic details:

- **`single_svg`**: Ensures exactly one `<svg>` block exists in the output (lines 58-60).

- **`finite_svg`**: Fails if the SVG contains `NaN`, `Infinity`, or `undefined` values (line 67).

- **`orthogonal_arrows`**: Detects any diagonal (non-orthogonal) arrow segments (lines 73-76).

- **`relationship_crossings`**: Flags proper-X crossings between relationships, treated as an error in showcase mode (lines 105-108).

- **`relationship_corridors`**: Flags ambiguous corridors where two relationships share a straight corridor (lines 112-115).

- **`container_border_runs`**: Detects relationships that follow the border of a composition frame, erroring only when `qualityGatesEnforced` is true (lines 118-120).

- **`route_rhythm`**: Checks for excessive bends or stretch beyond budget limits (2 bends, 1.35 stretch, 16px internal segment) (lines 124-126).

- **`legend_clearance`**: Guarantees arrows do not intersect the legend box (lines 31-44).

- **`label_route_clearance`**: Ensures labels maintain minimum clearance from unrelated routes, using a 2px threshold for standard profiles and 4px for showcase profiles (lines 97-100).

All checks feed into a `composition` summary object:

```javascript
composition = {
  profile: qualityProfile,               // "standard" or "showcase"
  status: compositionErrors ? 'fail' : 'pass',
  summary: { errors, warnings },
  metrics: { /* counts of crossings, corridors, etc. */ }
}

```

## Showcase-Quality Profile Enforcement

Showcase diagrams are marked with `data-quality-profile="showcase"` in the SVG output. For this profile:

- **Quality gates are enforced** (`qualityGatesEnforced = true`) unless the attribute `data-quality-gates="advisory"` is explicitly set.

- Any non-zero count for geometric checks is treated as a **hard error**, causing `composition.status` to become `"fail"` and the CLI to exit with status `1`.

- In standard mode, the same violations surface as **warnings**, allowing the diagram to pass while flagging issues for developers.

Thus, a showcase artifact must be **orthogonal**, contain **no crossing arrows**, **no ambiguous corridors**, **no border runs**, **respect label clearances**, and obey **route-budget limits**.

## Recording Validation in the Gallery Manifest

When `scripts/build-gallery.mjs` generates the gallery, it captures the checker's receipt and stores comprehensive metadata for each artifact:

- `checksPassed` / `checkCount`: Ratio of successful checks.
- `composition`: Full composition object including status and metrics.
- `nodeCount` / `edgeCount`: Graph size derived from the input IR.
- `artifactBytes` / `sourceBytes`: Byte sizes of generated HTML and source JSON.
- `artifactSha256` / `sourceSha256`: Deterministic SHA-256 hashes for integrity verification.
- `engineeringProfile`: Optional profile stamps (e.g., "DEPLOYMENT OWNERSHIP") displayed on gallery cards.

These values appear on the gallery UI as a **validation receipt** (e.g., "9/9 pass", "PASS", SHA-256 preview).

## Running Validation Locally

Execute the validation pipeline manually using the following commands:

```bash

# 1️⃣ Render a diagram (produces HTML with <svg>)

node archify/renderers/architecture/render-architecture.mjs \
    examples/web-app.architecture.json \
    output/web-app.html

# 2️⃣ Run the post-render checker (exit code 0 = showcase passes)

node scripts/check-render-output.mjs output/web-app.html

```

The checker outputs a JSON receipt:

```json
{
  "ok": true,
  "file": ".../output/web-app.html",
  "checks": [
    {"name":"single_svg","ok":true},
    {"name":"finite_svg","ok":true},
    {"name":"orthogonal_arrows","ok":true}
  ],
  "composition": {
    "profile":"showcase",
    "status":"pass",
    "metrics":{ "properCrossings":0, "ambiguousCorridors":0 }
  }
}

```

If any showcase-profile check fails, `ok` becomes `false` and the process exits with status `1`, causing automated gallery builds to abort.

## Summary

- Archify uses **AJV schema validation** on JSON input and **geometric checks** on SVG output to ensure diagram quality.
- The `scripts/check-render-output.mjs` script validates nine specific geometric properties including orthogonal arrows, relationship crossings, and label clearances.
- **Showcase quality** enforces hard errors for any geometric violations, while standard mode treats them as warnings.
- Validation receipts including SHA-256 hashes and composition metrics are stored in [`gallery/manifest.json`](https://github.com/tt-a1i/archify/blob/main/gallery/manifest.json) by `scripts/build-gallery.mjs`.
- The system uses `data-quality-profile` and `data-quality-gates` SVG attributes to control validation strictness.

## Frequently Asked Questions

### What triggers a showcase-quality validation failure?

A showcase-quality failure occurs when any geometric check—such as `relationship_crossings`, `container_border_runs`, or `label_route_clearance`—detects violations while `data-quality-profile="showcase"` is set and `data-quality-gates` is not `"advisory"`. The checker sets `composition.status` to `"fail"` and exits with code `1`, blocking gallery inclusion.

### How does the label clearance check differ between standard and showcase profiles?

The `label_route_clearance` check uses a 2px minimum clearance threshold for **standard** profiles, allowing minor overlaps to pass as warnings. For **showcase** profiles, the threshold increases to 4px, and any violation becomes a hard error that fails the validation.

### Where does Archify store validation receipts?

Validation receipts are stored in [`gallery/manifest.json`](https://github.com/tt-a1i/archify/blob/main/gallery/manifest.json) by the `scripts/build-gallery.mjs` script. Each receipt includes the number of checks passed, composition status, SHA-256 hashes of both source and artifact, file sizes, and graph metrics (node and edge counts).

### Can I bypass geometric checks during development?

Yes. Set the `data-quality-gates="advisory"` attribute on your SVG output to prevent the checker from treating violations as fatal errors. In advisory mode, geometric issues are reported as warnings in the composition summary but do not change the exit code, allowing iterative development without blocking renders.