# Archify Quality Profiles Explained: Standard vs. Showcase Differences

> Understand the Archify quality profiles standard vs showcase. Learn how standard treats composition issues as warnings and showcase elevates them to errors for production ready code.

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

---

**Archify's `standard` and `showcase` quality profiles differ in how strictly they enforce composition rules—`standard` treats composition issues as warnings for iterative development, while `showcase` elevates them to hard errors for polished, public-facing artifacts.**

When generating architectural diagrams in **Archify**, the `quality_profile` setting determines whether the renderer prioritizes development velocity or visual perfection. This guide breaks down the behavioral differences, exit semantics, and implementation details of each profile as defined in the `tt-a1i/archify` source code.

## What Are Archify Quality Profiles?

Quality profiles in Archify are **composition validation modes** that control how the engine handles aesthetic violations in diagram layouts. The profile is specified per-render and stored in the composition receipt for auditability.

According to [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) at line 21, the valid values are strictly enumerated:

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

```

## Standard Profile: Permissive Development Mode

The **`standard` profile** (default) is optimized for engineering workflows where diagrams evolve rapidly and visual perfection is secondary to functional correctness.

### Validation Behavior

- **Safety errors** (edges through nodes, non-finite paths) → **Hard failure**
- **Composition issues** (proper crossings, unrelated overlaps, container-border runs) → **Warning only**

### Exit Semantics

The CLI returns **exit code 0** even when warnings are present. The artifact is still generated, and warnings are recorded in the receipt for later inspection.

```bash

# Default standard profile behavior

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

# Both exit 0 with warnings in receipt; artifact produced

```

This permissive approach lets developers iterate on dense, real-world diagrams without being blocked by every visual imperfection.

## Showcase Profile: Strict Gallery Standard

The **`showcase` profile** is an opt-in strict mode for **polished Gallery or README artifacts** that represent the project to end-users.

### Validation Behavior

- **Safety errors** → **Hard failure** (unchanged from standard)
- **Composition errors** → **Hard failure** for:
  - Proper interior X crossings
  - Unrelated collinear overlaps
  - Routes collinear with container borders

### Exit Semantics

The CLI returns a **non-zero exit code** when any composition error is detected. The artifact is **rejected** and not produced for showcase generation.

```bash

# Strict showcase profile behavior

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

# Exits non-zero on composition errors; artifact rejected

```

## Side-by-Side Comparison

| Aspect | Standard Profile | Showcase Profile |
|--------|-----------------|------------------|
| **Primary use case** | Engineering diagrams, backward-compatible renders | Public Gallery/README artifacts |
| **Proper crossing** | Warning | Hard error |
| **Unrelated overlap** | Warning | Hard error (collinear only) |
| **Container-border run** | Warning | Hard error |
| **CLI exit code** | 0 (with warnings) | Non-zero (with errors) |
| **Artifact output** | Always produced | Rejected on error |

## Implementation in Source Code

The behavioral differences are validated in `archify/test/render-output-checks.test.mjs` at lines 246–250. This test suite confirms that:

```javascript
// Pseudocode based on test logic
test('proper crossing severity differs by profile', () => {
  const standardResult = render(diagram, { profile: 'standard' });
  assert(standardResult.warnings.includes('proper_crossing'));
  assert.strictEqual(standardResult.exitCode, 0);

  const showcaseResult = render(diagram, { profile: 'showcase' });
  assert(showcaseResult.errors.includes('proper_crossing'));
  assert.notStrictEqual(showcaseResult.exitCode, 0);
});

```

The design rationale is documented in [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md) at the profile table (lines 48–53), which explicitly maps each profile to its intended audience and strictness level.

## Checking Active Profile

To verify which profile applies to a validation run:

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

```

The JSON output includes the active profile:

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

```

## When to Use Each Profile

Use **`standard`** when:
- Rapidly iterating on complex diagrams
- Maintaining backward compatibility with existing renders
- Interior crossings are acceptable for clarity

Use **`showcase`** when:
- Generating official documentation assets
- Publishing to public Galleries or README files
- Visual polish reflects directly on project quality

## Summary

- **Standard** is the default, developer-friendly mode that warns on composition issues without blocking output—ideal for everyday engineering workflows.
- **Showcase** enforces a strict visual standard by elevating composition warnings to hard errors, ensuring only polished artifacts reach end-users.
- Both profiles share identical **safety validation**; the divergence applies exclusively to aesthetic concerns.
- Profile behavior is schema-defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), tested in `render-output-checks.test.mjs`, and documented in [`research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/research-visual-evolution-round-44.md).

## Frequently Asked Questions

### How do I set the quality profile in Archify CLI?

Pass `--quality <profile>` to any `render` or `validate` command. Valid values are `standard` (default if omitted) or `showcase`. Example: `archify render architecture diagram.json out.html --quality showcase`.

### Can I override the default standard profile globally?

No—Archify requires explicit per-command profile selection. This intentional design prevents accidental strictness changes in CI/CD pipelines where `showcase` failures would break automated builds.

### What happens to warnings in standard mode—are they visible?

Yes. Warnings are captured in the **composition receipt** (JSON output) and printed to stderr, but they do not affect the exit code or prevent artifact generation. Use `archify validate ... --json` to inspect them programmatically.

### Does showcase profile affect layout algorithms or just validation?

Only **validation**. Both profiles use identical layout engines; `showcase` simply applies stricter post-render checks. To improve layout quality, adjust diagram structure or routing parameters rather than switching profiles.