# Standard vs Showcase Quality Profiles in Archify: Complete Guide

> Understand the difference between Archify's standard and showcase quality profiles. Learn how each handles composition issues for your technical documentation.

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

---

**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](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), 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](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-46.md), 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

```bash

# 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](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-4.md), 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

```bash

# 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](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/README.md), 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), quality profiles can be baked into diagram definitions:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-4.md) | Showcase budget specification |
| [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md) | Side-by-side profile comparison table |
| [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.