Understanding Quality Profiles in Archify's Validation System

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

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

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.

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

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