Types of Validation Checks Archify Performs: A Complete Technical Guide

Archify executes eight distinct validation categories—from JSON-Schema compliance and topological integrity to geometric layout rules and engineering-profile matching—through a deterministic, JSON-serializable pipeline that produces structured diagnostic receipts.

Archify is an open-source diagram validation and rendering engine maintained in the tt-a1i/archify repository. Understanding the types of validation checks Archify performs is essential for CI/CD integration and ensuring architectural diagrams meet structural, geometric, and semantic standards before publishing.

JSON-Schema and Structural Validation

Every validation run begins in archify/renderers/shared/validator.mjs, where Archify confirms the input document conforms to the official Archify JSON schema. This check supports multiple diagram types—including architecture, workflow, dataflow, and lifecycle—ensuring mandatory fields exist and data types match the schema definitions. The validateSchema() function returns a result object with an ok boolean and an errors array if the document violates structural constraints.

Topology and Identity Checks

After schema validation, the system performs topology and identity validation to guarantee graph integrity. This phase detects:

• Duplicate IDs across nodes and edges
• Missing node references in edge definitions
• Malformed edge definitions lacking source or target identifiers

These checks ensure every graph element possesses a stable, unique identifier required for downstream rendering and contract validation.

Geometric and Layout Validation

Geometric rules are enforced by archify/renderers/shared/geometry.mjs. This module validates:

• Node overlap detection: Ensures components do not occupy identical coordinates
• Edge intersection rules: Verifies edges do not traverse forbidden regions
• Reserved-area compliance: Confirms diagram elements respect exclusion zones
• Edge-through-node violations: Prevents lines from passing through component boundaries

The geometry engine operates on normalized coordinates and returns specific diagnostic codes (e.g., clean-flow/edge-through-node) when violations occur.

Grid Placement Validation

For architecture diagrams utilizing matrix layouts, archify/renderers/architecture/grid.mjs executes grid placement validation. This check ensures:

• Row and column matrices are well-formed
• Each grid cell contains at most one component
• Explicit position overrides remain within matrix bounds
• Cell occupancy constraints are satisfied

Grid validation runs prior to geometric checks to establish the coordinate framework used by the layout engine.

Visual Quality and Readability Checks

Archify applies the "showcase" quality profile through archify/renderers/shared/desktop-readability.mjs. These validation checks enforce:

• Minimum pixel clearance between elements (optimized for 1440 px viewports)
• Label readability standards (contrast ratios and font sizes)
• Edge-stroke width compliance
• Overall visual density limits

Enable these checks by passing --quality showcase to the CLI for publication-ready diagrams.

Engineering Profile and Contract Validation

The system validates engineering profiles in archify/renderers/shared/engineering-profiles.mjs. This verification confirms that a diagram's declared profile (e.g., deployment-ownership) matches the required profile for the artifact type, linking the diagram to concrete deployment metadata and organizational ownership rules.

Additionally, scripts/check-release-identity.mjs performs release manifest validation via validateLocalRelease() and validateStableUpdateManifest() functions. These checks ensure packaging integrity when publishing Archify-based skills or stable updates.

Diagnostics and Automated Repair

When validation fails, archify/renderers/shared/diagnostics.mjs generates structured diagnostic objects containing:

• Human-readable error messages
• Machine-readable error codes
• Subject references (node/edge IDs)
• Evidence objects with coordinates or values
• Supported fixes arrays with auto-repair instructions

The repairReceipt() function consumes these diagnostics to apply suggested fixes—such as rerouting edges through alternative nodes—and produces a modified diagram that can be re-validated.

Running Validation: CLI and Programmatic Examples

CLI Validation

Validate an architecture diagram and receive a JSON receipt:

archify validate architecture path/to/diagram.json --json

Apply the showcase quality profile for desktop readability checks:

archify validate architecture path/to/diagram.json --quality showcase --json

Programmatic Validation

Import validation functions directly in Node.js applications:

import { validateSchema } from './archify/renderers/shared/validator.mjs';
import { validateArchitecture } from './archify/renderers/architecture/render-architecture.mjs';
import { readFileSync } from 'fs';

const doc = JSON.parse(readFileSync('path/to/diagram.json', 'utf8'));

// Schema validation
const schemaResult = validateSchema('architecture', doc);
if (!schemaResult.ok) {
  console.error('Schema errors:', schemaResult.errors);
}

// Full validation with geometry and readability
const receipt = validateArchitecture(doc, { quality: 'showcase' });
console.log('Checks passed:', receipt.checksPassed);
console.log('Diagnostics:', receipt.diagnostics);

Automated Repair Workflow

Apply suggested fixes programmatically:

import { repairReceipt } from './archify/renderers/shared/diagnostics.mjs';

const receipt = validateArchitecture(doc, { quality: 'showcase' });
const fix = receipt.diagnostics.find(d => 
  d.code === 'clean-flow/edge-through-node'
);

if (fix && fix.suggestedFixes.length > 0) {
  const repaired = repairReceipt(receipt, fix.suggestedFixes[0]);
  // Save repaired.document for re-validation
}

Summary

• JSON-Schema validation enforces document structure and data types via validator.mjs.
• Topology checks eliminate duplicate IDs and malformed graph references.
• Geometry validation prevents visual collisions and layout violations in geometry.mjs.
• Grid validation ensures matrix-based diagrams maintain proper cell occupancy.
• Readability checks apply showcase-quality standards for publication-ready output.
• Engineering profiles link diagrams to deployment metadata and organizational rules.
• Release validation secures packaging integrity through manifest checks.
• Diagnostic receipts provide structured error reports and auto-repair capabilities.

Frequently Asked Questions

How does Archify handle schema validation for different diagram types?

Archify dispatches to type-specific JSON schemas through the validateSchema() function in archify/renderers/shared/validator.mjs. Each diagram type (architecture, workflow, dataflow) loads its respective schema definition, validating mandatory fields and type constraints before proceeding to geometric checks.

Can Archify automatically fix validation errors?

Yes. When the validation pipeline detects violations, archify/renderers/shared/diagnostics.mjs generates diagnostic objects containing suggestedFixes arrays. The repairReceipt() function consumes these suggestions to apply automated corrections—such as rerouting edges or adjusting node positions—returning a repaired diagram document ready for re-validation.

What is the difference between geometry validation and grid placement validation?

Grid placement validation (grid.mjs) operates on the logical matrix structure of architecture diagrams, ensuring cells contain single components and coordinates fit the row/column schema. Geometry validation (geometry.mjs) operates on the rendered pixel coordinates, checking for physical overlaps, edge intersections, and viewport clearance regardless of the underlying grid system.

How do I integrate Archify validation into a CI pipeline?

Invoke the CLI with the --json flag to receive machine-readable receipts. The exit code reflects validation status (checksPassed), while stdout contains a JSON object with checkCount and diagnostics arrays. Parse this output in GitHub Actions, GitLab CI, or Jenkins to gate merges based on diagram integrity or quality profile compliance.

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