# Archify Validation System and Quality Profiles: A Complete Technical Guide

> Explore the Archify validation system and its quality profiles. This guide details how Archify enforces diagram-as-data contract rules with configurable profiles for strict or lenient constraints.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-29

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`):

```bash
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:

```bash
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:

```yaml

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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/archify/src/validation.ts) and [`archify/src/cli.ts`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), while the runtime logic that applies profile-specific severity mapping resides in [`archify/src/validation.ts`](https://github.com/tt-a1i/archify/blob/main/archify/src/validation.ts). Example diagrams demonstrating both profiles are available in `archify/examples/`.