Archify Validation System and Quality Profiles: A Complete Technical Guide

The Archify validation system checks diagram-as-data files (JSON/YAML) against schema-defined contract rules, using configurable quality profiles ("standard" or "showcase") to enforce strict or lenient geometric, routing, and labeling constraints before rendering.

Archify is an open-source tool from the tt-a1i/archify repository that treats architecture diagrams as structured data. Before any diagram is rendered, the Archify validation system ensures its metadata, geometry, and composition satisfy specific quality thresholds defined by the selected quality profile.

How the Validation System Works

The validation pipeline processes diagram files through five distinct phases, from schema loading to final reporting.

Schema Load and Profile Resolution

Every diagram file must conform to the JSON schema defined in archify/schemas/architecture.schema.json. This schema specifies required fields, enum values, and the quality_profile property within the meta section.

If meta.quality_profile is omitted, the system defaults to standard. Valid values are "standard" and "showcase".

Rule Set Selection

Based on the resolved profile, the validator—implemented in archify/src/validation.ts—constructs a rule set that maps each validation rule to a severity level (error, warning, or info). The showcase profile elevates many warnings to errors, while standard tolerates minor visual imperfections.

Graph Traversal and Validation

The validator walks the diagram graph and applies profile-specific checks across four categories:

• Geometry – Validates proper crossings, container-border runs, and micro-segment lengths
• Routing – Verifies edge-to-edge clearance and direction-change budgets
• Labels – Checks legibility, non-overlap, and required annotation counts
• Composition – Analyzes overall metrics such as properCrossings and borderRuns

Receipt Generation

As implemented in archify/src/cli.ts, the system outputs a receipt listing each rule, its status (PASS, WARN, ERROR), and profile-specific severity. The CLI returns a non-zero exit code if any error exists for the active profile.

Understanding Quality Profiles

Archify provides two distinct quality profiles that serve different stages of the diagram lifecycle.

Standard Profile

The standard profile targets "working diagrams" suitable for internal drafts and rapid iteration. It restricts errors to hard violations—such as illegal edge crossings—while issuing warnings for style-guide suggestions like excessive bends. Use this profile for early-stage sketches and prototype reviews.

Showcase Profile

The showcase profile enforces "polished delivery" standards for stakeholder presentations or published galleries. It treats visual readability issues as errors, including any edge crossings or insufficient clearance, and imposes stricter limits on bend counts and micro-segments. A diagram that passes the showcase profile automatically satisfies the standard profile, as the former is a strict superset of the latter.

Declare the profile in your diagram's metadata:

{
  "meta": {
    "quality_profile": "showcase",
    "animation": "trace",
    "viewBox": [880, 900]
  }
}

Practical Usage Examples

Validating with the Default Standard Profile

Run the following command to validate a diagram using the standard profile (or whatever is specified in meta.quality_profile):

archify validate path/to/diagram.json

The CLI prints a concise receipt and exits with code 0 only if no errors exist for the active profile.

Forcing the Showcase Profile

Override the file's metadata to enforce showcase strictness and output JSON for programmatic consumption:

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

This outputs the full receipt, including numeric metrics and detailed rule statuses.

CI Pipeline Integration

Gate merges in GitHub Actions by running showcase validation:

# .github/workflows/archify.yml

name: Diagram CI
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Archify
        run: npm ci
      - name: Validate diagrams
        run: |
          archify validate diagrams/**/*.json --quality showcase --json > receipt.json
          jq '.ok' receipt.json  # exits non-zero if validation fails

Programmatic Validation in Node.js

Import the validation engine directly to integrate checks into custom tooling:

import { validateDiagram } from '@tt-a1i/archify';

const diagram = await import('./my-diagram.json');
const result = await validateDiagram(diagram, { profile: 'showcase' });

if (!result.ok) {
  console.error('Validation failed:', result.errors);
  process.exit(1);
}

Summary

• The Archify validation system processes diagram-as-data files through a five-stage pipeline defined in archify/src/validation.ts and archify/src/cli.ts.
• Two quality profiles—standard and showcase—control validation strictness, with showcase being a superset of standard constraints.
• Profile selection occurs via the meta.quality_profile field in archify/schemas/architecture.schema.json, defaulting to standard when unspecified.
• The validator checks geometry, routing, labels, and composition, outputting a structured receipt with PASS, WARN, or ERROR statuses.
• CI pipelines can enforce quality gates using the --quality flag and JSON output mode.

Frequently Asked Questions

What happens if I don't specify a quality profile in my diagram file?

If the meta.quality_profile key is missing from your diagram's metadata, the Archify validation system automatically defaults to the standard profile. This behavior is defined in the JSON schema at archify/schemas/architecture.schema.json, ensuring backward compatibility for existing diagrams.

Can a diagram pass the showcase profile but fail the standard profile?

No. The showcase profile is a strict superset of the standard profile, meaning it enforces all standard rules plus additional strictures. Any diagram that satisfies showcase requirements automatically complies with standard requirements, though the inverse is not true.

How does the validation system report errors differently between profiles?

According to archify/src/validation.ts, each profile maintains a distinct severity map for the same underlying rules. A geometry issue might trigger a warning in standard mode but an error in showcase mode. The CLI receipt—generated by archify/src/cli.ts—reflects these profile-specific severities while maintaining consistent rule identifiers.

Where are the quality profile definitions stored in the repository?

The permissible values for quality profiles (standard, showcase) are enumerated in archify/schemas/architecture.schema.json, while the runtime logic that applies profile-specific severity mapping resides in archify/src/validation.ts. Example diagrams demonstrating both profiles are available in archify/examples/.

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