# Understanding Quality Profiles in Archify's Validation System

> Explore Archify's validation system quality profiles: showcase, draft, and preview. Tune strictness for production checks or render-guarantee tests with the --quality flag.

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

---

**Archify offers three built-in quality profiles—`showcase`, `draft`, and `preview`—that let you tune validation strictness from exhaustive production checks to minimal render-guarantee tests using the `--quality` CLI flag or programmatic `quality` parameter.**

Archify validates typed JSON architecture and flow descriptions before rendering them into diagrams, ensuring structural integrity before visualization. The **quality profiles in Archify's validation system** provide granular control over which validators execute and how strictly they enforce rules, allowing you to balance validation speed against output correctness depending on your workflow stage.

## The Three Quality Profiles Explained

Archify implements a tiered validation strategy through the `QualityProfile` enumeration defined in [`archify/validation/quality.js`](https://github.com/tt-a1i/archify/blob/main/archify/validation/quality.js). Each profile selects a specific validator chain that determines which checks run during the validation phase.

### Showcase Profile (Production-Grade Validation)

The **showcase** profile runs the full suite of validators, including schema validation, layout analysis, route-label clearance checks, and visual-preset verification. When failures occur, this profile generates a **machine-readable repair receipt** that details exactly what must be fixed to achieve compliance.

Use this profile when generating production-ready artifacts intended for publication, sharing, or formal review processes where visual correctness is mandatory.

### Draft Profile (Rapid Iteration)

The **draft** profile performs a lighter validation pass that executes schema and basic layout checks only. It explicitly skips route-label and visual-preset rules, allowing minor visual glitches that are acceptable during early-stage development.

This profile is ideal for rapid prototyping and brainstorming sessions where you need fast feedback without waiting for exhaustive validation to complete.

### Preview Profile (Minimal Validation)

The **preview** profile executes only the minimal set of checks required to ensure the JSON can be rendered successfully. No layout or route-label validation is performed, making this the fastest option when you simply need to visualize the diagram without caring about strict correctness.

Use this profile for "preview-only" workflows where the goal is quick visual confirmation rather than validated output.

## How Quality Profiles Work in the Source Code

According to the `tt-a1i/archify` source code, the CLI entry point in `archify/bin/archify.mjs` parses the `--quality` flag (short form `-q`) and maps the string value to the internal `QualityProfile` enum. The enum entries—`showcase`, `draft`, and `preview`—each select a distinct validator chain configuration.

The mapping logic resides in the validation module, specifically within [`archify/validation/quality.js`](https://github.com/tt-a1i/archify/blob/main/archify/validation/quality.js), where each profile constant is bound to its corresponding array of validator functions. This architecture allows the system to skip expensive checks like route-label clearance when running under the `draft` or `preview` profiles, significantly reducing execution time for large architecture files.

## Using Quality Profiles in Practice

You can specify quality profiles via the command line or programmatically through the JavaScript API.

### CLI Usage

Run the `validate` or `preview` commands with the `--quality` flag:

```bash

# Full, production-ready validation with machine-readable diagnostics

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

# Faster validation for rapid iteration

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
  --quality draft

# Minimal validation for quick visual previews

node archify/bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality preview

```

### Programmatic Usage

Import the `validate` function and pass the `quality` option:

```javascript
import { validate } from 'archify';

await validate({
  type: 'workflow',
  source: './examples/agent-tool-call.workflow.json',
  quality: 'showcase',   // Options: "showcase" | "draft" | "preview"
  json: true,
});

```

## Summary

- **Archify's validation system** provides three distinct quality profiles that trade strictness for speed.
- The **showcase** profile enforces complete validation including route-label and visual-preset checks, generating repair receipts for any failures.
- The **draft** profile limits validation to schema and basic layout checks, ideal for rapid prototyping workflows.
- The **preview** profile performs only render-guarantee checks, ensuring the JSON can be visualized without enforcing layout correctness.
- Profile selection is handled in `archify/bin/archify.mjs` and mapped to the `QualityProfile` enum in [`archify/validation/quality.js`](https://github.com/tt-a1i/archify/blob/main/archify/validation/quality.js).

## Frequently Asked Questions

### What is the difference between the draft and preview quality profiles?

The **draft** profile validates schema structure and basic layout rules, ensuring your architecture file is structurally sound while allowing minor visual imperfections. The **preview** profile skips all layout and route-label validation entirely, checking only whether the JSON can be rendered at all. Use `draft` when you need structural integrity but not visual polish; use `preview` when you only need to see the diagram quickly.

### How do I set a quality profile as the default for all Archify commands?

The Archify CLI does not currently persist default quality profile settings between commands. You must specify the `--quality` flag (or `-q` short form) explicitly for each invocation. For repeated operations, consider wrapping commands in shell aliases or npm scripts that include your preferred profile flag.

### Can I create custom quality profiles in Archify?

The current implementation in [`archify/validation/quality.js`](https://github.com/tt-a1i/archify/blob/main/archify/validation/quality.js) supports only the three built-in enum values: `showcase`, `draft`, and `preview`. The validator chains are hardcoded for each profile, and the CLI validates input against these specific strings. Custom profiles would require modifying the source code to extend the `QualityProfile` enumeration and register additional validator chains.

### Which quality profile should I use in CI/CD pipelines?

Use the **showcase** profile in CI/CD pipelines and automated build systems. This ensures that all architecture diagrams meet production standards for schema correctness, layout integrity, route-label clearance, and visual-preset compliance before deployment. The profile's generation of machine-readable repair receipts also facilitates automated failure analysis when validation errors occur.