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

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.

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:

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:

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

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

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