Standard vs Showcase Quality Profiles in Archify: Complete Guide

The standard profile tolerates visual composition issues as warnings, while the showcase profile enforces strict presentation-ready standards and treats the same issues as hard errors.

Archify provides two quality profiles that control how strictly visual-composition rules are applied during diagram rendering and validation. These profiles share the same underlying Composition Quality Contract from the Fireworks tech-graph project, but apply different tolerance thresholds depending on whether you're producing engineering drafts or polished deliverables.

How Quality Profiles Work in Archify

Quality profiles are specified through either the meta.quality_profile field in your diagram metadata or the --quality CLI flag. The system evaluates nine artifact checks against composition thresholds, with the profile determining whether violations are logged as warnings or raised as fatal errors.

Default Behavior

• Standard: Implicit default when meta.quality_profile is omitted or when using --quality standard
• Showcase: Explicit opt-in via meta.quality_profile: "showcase" or --quality showcase

According to the schemas documentation, the meta.quality_profile field directly influences how renderers apply composition rules during both validation and delivery operations.

Standard Quality Profile: Engineering-Focused Permissiveness

The standard profile prioritizes rapid iteration and CI compatibility over pixel-perfect output.

Composition Thresholds in Standard Mode

Threshold	Standard Value
Maximum bends	Up to 12
Stretch tolerance	Approximately 5.0
Minimum segment	Zero-length allowed
Line crossings	Permitted (logged as warnings)

As documented in research-visual-evolution-round-46, the standard profile generates a receipt that records warnings without blocking delivery. X-crossings appear in the warning log but do not prevent successful completion.

CLI Behavior with Standard Profile

# Validate with standard profile – exits 0 even with composition warnings

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

# Deliver tolerates warnings and produces HTML regardless

node bin/archify.mjs deliver architecture examples/checkout-platform.base.architecture.json \
    /tmp/arch.html --quality standard

Both commands return exit code 0 and produce usable artifacts even when the receipt lists composition warnings. This makes standard ideal for automated pipelines that must not fail on cosmetic issues.

Showcase Quality Profile: Presentation-Ready Strictness

The showcase profile enforces premium visual standards suitable for external stakeholders and public documentation.

Composition Budget in Showcase Mode

Threshold	Showcase Value
Line crossings	Zero tolerance
Bridges	Not permitted
Maximum bends	Maximum 2
Node spacing	Budgeted minimum enforced
Container gutters	Budgeted spacing required

The showcase budget is defined in research-visual-evolution-round-4, which specifies that any violation of these thresholds is treated as a failure preventing successful rendering. The receipt only receives a SHOWCASE · PASS flag when all nine artifact checks succeed with zero composition errors.

CLI Behavior with Showcase Profile

# Validate with showcase profile – non-zero exit on any composition breach

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

# Deliver aborts unless diagram passes all checks

node bin/archify.mjs deliver architecture examples/checkout-platform.base.architecture.json \
    /tmp/arch.html --quality showcase

As implemented in the renderers README, the showcase profile causes validate operations to yield non-zero exit codes for any composition breach, and deliver operations to abort entirely rather than produce substandard output.

When to Use Each Quality Profile

Choose Standard For

• Draft diagrams during rapid iteration
• Internal design reviews where quick feedback matters
• CI/CD pipelines that must complete regardless of visual quirks
• Automated documentation builds where minor crossings are acceptable

Choose Showcase For

• Final assets for public documentation
• Marketing materials and stakeholder presentations
• Continuous delivery gates requiring "show-ready" artifacts
• Any context where visual fidelity is non-negotiable

Profile Configuration in Source Files

According to archify/schemas/README.md, quality profiles can be baked into diagram definitions:

{
  "meta": {
    "quality_profile": "showcase"
  },
  "nodes": [...],
  "edges": [...]
}

When meta.quality_profile is omitted, the system implicitly defaults to standard. Explicit declaration overrides this behavior for that specific diagram.

Key Implementation Files

File Path	Relevance
archify/schemas/README.md	Documents meta.quality_profile field behavior
archify/renderers/*/README.md	Renderer-specific profile implementations (dataflow, workflow, lifecycle)
docs/research-visual-evolution-round-4.md	Showcase budget specification
docs/research-visual-evolution-round-44.md	Side-by-side profile comparison table
archify/references/delivery-contract.md	CLI usage patterns with --quality showcase

Summary

• Standard profile allows up to 12 bends, tolerates crossings, and exits 0 with warnings—optimized for engineering workflows
• Showcase profile enforces zero crossings, no bridges, maximum 2 bends, and exits non-zero on any violation—optimized for presentation quality
• Both profiles depend on the same meta.quality_profile field and --quality CLI flag, differing only in threshold strictness
• The delivery contract in archify/references/delivery-contract.md governs how each profile affects HTML generation and receipt marking

Frequently Asked Questions

What happens if I omit the quality profile entirely?

Archify defaults to the standard profile. Your diagrams will validate and render successfully even with composition warnings, and the CLI will exit 0. This default is hardcoded in the renderer initialization logic across all supported diagram types.

Can I override a baked-in showcase profile from the command line?

Yes. The --quality CLI flag takes precedence over meta.quality_profile. If your source file declares "quality_profile": "showcase" but you run with --quality standard, the standard thresholds apply for that execution.

Why does showcase allow zero line crossings when standard permits them?

The showcase profile targets presentation contexts where every visual element must be immediately legible. Line crossings create cognitive load and appear unpolished to external audiences. The engineering-focused standard profile prioritizes information density and rendering speed over this visual purity.

How do I check which profile was used for a rendered diagram?

Examine the receipt generated by validation or delivery operations. Standard profiles produce receipts listing warnings without blocking status. Showcase profiles include a SHOWCASE · PASS flag only when all nine artifact checks succeed—any failure omits this flag and marks the receipt as failed.

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