# Standard vs Showcase Quality Profiles in Archify: Key Differences Explained

> Understand the key differences between Archify's standard and showcase quality profiles. Learn how showcase promotes composition issues to hard errors, blocking polished artifacts.

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

---

**Archify's `standard` quality profile treats composition issues as warnings with exit code 0, while `showcase` promotes the same checks to hard errors with non-zero exit codes to block polished artifacts.**

When rendering architecture diagrams in Archify, you choose between two **quality profiles** that determine how strictly the tool validates visual composition. These profiles exist in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) as an enum with values `["standard","showcase"]`【line 21】. Understanding their differences helps you iterate faster during development while maintaining high standards for public-facing documentation.

## How the Standard Profile Works

The **standard** profile is Archify's default mode for everyday engineering workflows.

- **Safety errors** (edges through nodes, non-finite paths) **fail immediately**
- **Composition issues** (proper crossings, overlaps, container-border runs) become **warnings only**
- CLI returns **exit code 0** even when warnings exist
- The receipt contains warnings for inspection without blocking the artifact

This permissive approach lets developers work with dense, real-world diagrams without interruption.

## How the Showcase Profile Works

The **showcase** profile is an opt-in stricter mode for polished Gallery and README artifacts.

- Safety errors still fail as in standard
- **Composition checks become hard errors** for:
  - Proper interior X crossings
  - Unrelated collinear overlaps
  - Routes running collinearly along container borders
- CLI returns **non-zero exit code** when any composition error exists
- The artifact is **rejected for showcase generation**

According to the design document in [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md)【profile table, lines 48-53】, this profile enforces "a stricter visual standard for the public-facing examples."

## Practical Usage Examples

Select your profile via the `--quality` flag:

```bash

# Default standard profile — warnings don't block output

archify render architecture diagram.json out.html

# → exits 0, receipt contains any composition warnings

# Explicit showcase profile — composition errors block output

archify render architecture diagram.json out.html --quality showcase

# → exits non-zero if proper X crossing or similar error found

```

Inspect the active profile programmatically:

```bash
archify validate architecture diagram.json --json

```

The JSON output includes `"composition.profile": "standard"` or `"showcase"` depending on what was resolved.

## Behavioral Differences in Test Suite

The test file `archify/test/render-output-checks.test.mjs`【lines 246-250】demonstrates the core behavioral difference: a proper crossing is recorded as a **warning** under standard but as an **error** under showcase. This test validates that the profile selection directly affects receipt severity levels and exit semantics.

## When to Use Each Profile

| Scenario | Recommended Profile |
|----------|-------------------|
| Daily development and iteration | `standard` |
| CI/CD with existing diagrams | `standard` |
| Public documentation and READMEs | `showcase` |
| Gallery publications and demos | `showcase` |
| Backwards-compatible rendering | `standard` |

## Summary

- **Standard profile**: Default, warning-centric, exit 0 on composition issues, ideal for engineering workflows
- **Showcase profile**: Opt-in, error-centric, non-zero exit on composition issues, blocks polished artifact generation
- **Configuration**: Set via `--quality` flag or implied by default; enum declared in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)
- **Validation**: Test suite confirms warning vs. error behavior per profile

## Frequently Asked Questions

### How do I enable the showcase quality profile in Archify?

Pass `--quality showcase` to any `archify render architecture` command. Without this flag, the tool defaults to `standard`.

### Does the showcase profile ignore safety errors?

No. Both profiles treat safety errors (edges through nodes, non-finite paths) as hard failures. The difference lies strictly in composition validation severity.

### Where is the quality profile defined in the codebase?

The allowed values are declared in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)【line 21】. Design rationale appears in [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md), with behavioral tests in `archify/test/render-output-checks.test.mjs`.

### Can I migrate a standard diagram to showcase without re-rendering?

Run `archify validate architecture diagram.json --quality showcase --json` first. This checks whether your existing diagram would pass showcase criteria before you attempt a render that might fail with a non-zero exit code.