# Archify Quality Profiles: Standard vs. Showcase Differences Explained

> Understand Archify quality profiles. Learn the key differences between standard and showcase profiles for composition checks and build success.

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

---

**In Archify, `standard` (the default) treats composition issues like proper crossings and overlaps as warnings that don't block rendering, while `showcase` elevates those same checks to hard errors that fail the build and reject the artifact.**

The `tt-a1i/archify` repository implements two **quality profiles** that control how strictly diagram composition is validated. These profiles determine whether visual imperfections generate mere feedback or halt the pipeline entirely.

## How the Profiles Work

Archify evaluates diagrams against two categories of checks:

- **Safety errors**: Issues that break rendering (edges through nodes, non-finite paths)
- **Composition issues**: Visual imperfections (proper crossings, unrelated overlaps, container-border runs)

The profile you choose decides which category composition issues fall into.

## Standard Profile: Permissive Engineering Mode

The **standard profile** is optimized for iterative development of real-world diagrams.

Under this mode:

- Safety errors **fail** and block rendering
- Composition issues become **warnings** that don't abort the process
- The CLI returns **exit code 0** even when warnings exist
- The receipt includes warnings for inspection

This profile allows developers to work with dense, complex diagrams without every visual imperfection blocking their workflow.

The schema defines `"standard"` as the default value in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) at line 21:

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

```

## Showcase Profile: Strict Quality Gates

The **showcase profile** enforces polished visual standards for public-facing artifacts.

Under this mode:

- Safety errors **still fail** (unchanged from standard)
- Composition checks become **hard errors** for:
  - Proper interior X crossings
  - Unrelated collinear overlaps
  - Routes running collinearly along container borders
- The CLI returns a **non-zero exit code** on any error
- The artifact is **rejected** for showcase generation

This profile ensures README images and gallery examples meet strict visual quality standards.

## Behavioral Differences in Code

The test suite in `archify/test/render-output-checks.test.mjs` (lines 246-250) confirms the divergence. A proper crossing that generates a warning under **standard** becomes a blocking error under **showcase**.

Design documentation in [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md) (lines 48-53) explains this intentional separation: standard prioritizes developer velocity, while showcase prioritizes presentation quality.

## Practical Usage Examples

### Default Standard Rendering

```bash

# Implicit default

archify render architecture diagram.json out.html

# Explicit standard (equivalent)

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

```

Returns exit code 0 with warnings in the receipt. The HTML artifact is produced regardless of composition issues.

### Strict Showcase Rendering

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

```

Returns non-zero exit code if proper crossings, overlaps, or border runs are detected. The artifact is rejected.

### Inspecting Active Profile

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

```

Output includes the resolved profile:

```json
{
  "composition": {
    "profile": "standard"
  }
}

```

## When to Use Each Profile

| Use Case | Recommended Profile | Rationale |
|----------|---------------------|-----------|
| Daily development, CI diagrams | **standard** | Don't block builds on cosmetic issues |
| Internal documentation | **standard** | Velocity over pixel perfection |
| Public README/Gallery images | **showcase** | Guarantee polished presentation |
| Release artifacts | **showcase** | Prevent substandard visuals from shipping |

## Summary

- **Standard profile** (`archify/schemas/architecture.schema.json#L21`): warnings for composition issues, exit code 0, designed for engineering workflows
- **Showcase profile**: hard errors for composition issues, non-zero exit code, designed for public artifacts
- **Same safety checks** apply regardless of profile; only composition severity changes
- **Test verification**: `archify/test/render-output-checks.test.mjs#L246-L250` validates the warning vs. error behavior

## Frequently Asked Questions

### How do I switch between standard and showcase profiles in Archify?

Pass `--quality showcase` or `--quality standard` to any `archify render` command. If omitted, `standard` is used. The profile is also configurable in your [`architecture.json`](https://github.com/tt-a1i/archify/blob/main/architecture.json) under the `composition.profile` field.

### Does the showcase profile catch more errors than standard?

No. Both profiles run identical validation checks. The difference is severity: **standard** logs composition issues as warnings while **showcase** treats them as fatal errors. Safety errors (edges through nodes, non-finite paths) always fail regardless of profile.

### Can I use showcase profile in CI but standard locally?

Yes. Set `composition.profile: "standard"` in your configuration file for local development, then override in CI: `archify render ... --quality showcase`. This catches visual regressions before they reach public documentation.