Archify Quality Profiles: Standard vs Showcase Checks Explained

Archify supports two distinct quality profiles—standard and showcase—that determine validation strictness, with showcase enforcing tighter visual budgets and composition rules required for public-facing diagrams.

Archify’s rendering pipeline uses named quality profiles to control how strictly diagram layouts are judged. The standard profile guarantees baseline correctness while allowing minor visual flexibility, whereas the showcase profile enforces the highest standards for release-grade artifacts. According to the tt-a1i/archify source code, the active profile is resolved from either CLI flags or the meta.quality_profile field and drives validation logic in the workflow compiler.

Standard vs Showcase: Core Differences

The two profiles differ fundamentally in validation scope and failure thresholds.

Standard Profile

• Purpose: Provides baseline layout guarantees for internal documentation and rapid iteration.
• Validation Scope: Performs basic schema validation, geometry sanity checks (no overlapping nodes), and minimal visual-budget verification.
• Failure Behavior: Reports composition errors as warnings rather than hard failures.
• Default Status: Implicit when no profile is specified or when meta.quality_profile is omitted.

Showcase Profile

• Purpose: Enforces strict visual-budget standards for public-facing artifacts, Proof Lab diagrams, and release-grade exports.
• Validation Scope: Includes all standard checks plus stricter limits on corridor widths, bend radii, and composition quality contracts such as "no opaque crossings" and tighter label-to-route clearance.
• Failure Behavior: Treats composition errors as hard failures, returning a composition status of fail in the validation receipt.
• Activation: Explicitly set via --quality showcase CLI flag or "quality_profile": "showcase" in the source JSON.

Profile Resolution Logic

Archify resolves the active quality profile through a cascading priority system implemented in the workflow compiler.

In archify/renderers/workflow/workflow-compiler.mjs at lines 772–775, the resolution logic falls back from the CLI argument to the metadata field:

const resolvedQualityProfile = qualityProfile || inputWorkflow.meta?.quality_profile;

If the resolved profile differs from the stored value, Archify injects the new value before proceeding to validation. The renderer additionally checks the ARCHIFY_QUALITY_PROFILE environment variable in archify/renderers/workflow/render-workflow.mjs at line 16:

qualityProfile: process.env.ARCHIFY_QUALITY_PROFILE || workflow.meta?.quality_profile,

Schema and Validation Implementation

The allowed enum values are defined in the JSON schema at schemas/workflow.schema.json lines 36–38:

"quality_profile": { "enum": ["standard","showcase"] }

Downstream validators import these constraints. The shared geometry validator in archify/renderers/shared/generated-validators.mjs (lines 13–14) uses this enum to determine which visual-budget thresholds to apply during layout validation.

CLI Usage and Practical Examples

Validate diagrams using either profile via the archify CLI.

Use the default standard profile for quick validation:

archify validate architecture diagram.json --json

Force the stricter showcase profile explicitly:

archify validate architecture diagram.json --quality showcase --json

Alternatively, embed the profile directly in the source JSON to avoid CLI flags:

{
  "schema_version": 2,
  "diagram_type": "architecture",
  "meta": {
    "title": "Demo",
    "quality_profile": "showcase"
  }
}

The validation receipt reflects the active profile and composition status:

{
  "ok": true,
  "composition": "pass",
  "quality_profile": "showcase",
  "checks": {
    "layout": "pass",
    "visual_budget": "pass"
  }
}

Showcase validation may also increase export quality settings, such as PNG compression ratios set to 0.95, to ensure crisp visuals in final artifacts.

Summary

• Archify quality profiles determine validation strictness through standard (baseline) and showcase (strict) modes.
• The profile resolves from CLI flags (--quality), environment variables (ARCHIFY_QUALITY_PROFILE), or meta.quality_profile in source JSON.
• Showcase mode enforces tighter visual budgets and treats composition errors as hard failures, while standard mode reports them as warnings.
• Key implementation files include workflow-compiler.mjs for resolution, workflow.schema.json for schema definition, and generated-validators.mjs for threshold enforcement.

Frequently Asked Questions

What is the difference between standard and showcase quality profiles in Archify?

Standard profiles validate basic geometry and schema correctness while allowing minor visual imperfections to pass as warnings. Showcase profiles enforce strict visual budgets, prohibit opaque crossings, and require tight label-to-route clearances, treating any composition error as a validation failure.

How do I set the quality profile in Archify?

You can set the profile via the --quality CLI flag (e.g., --quality showcase), by setting the ARCHIFY_QUALITY_PROFILE environment variable, or by adding "quality_profile": "showcase" to the meta object in your diagram JSON. The CLI flag takes precedence over environment variables and metadata fields.

What happens if a diagram fails showcase validation?

When showcase validation fails, the CLI exits with an error and the JSON receipt contains "composition": "fail" along with specific error codes such as ERR_QUALITY_LIMIT_EXCEEDED. The diagram will not be considered valid for export or release despite being structurally sound.

Which source files control quality profile validation in Archify?

The resolution logic resides in archify/renderers/workflow/workflow-compiler.mjs (lines 772–775), schema definitions are in schemas/workflow.schema.json (lines 36–38), and threshold enforcement occurs in archify/renderers/shared/generated-validators.mjs (lines 13–14). The CLI entry point at archify/bin/archify.mjs handles flag parsing.

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