# Archify Quality Profiles and Engineering Contracts Explained

> Discover Archify's quality profiles standard and showcase and engineering contracts. Enforce visual guarantees and interoperability for your diagram artifacts.

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

---

**Archify uses two primary quality profiles—`standard` and `showcase`—alongside formal engineering contracts to enforce strict visual guarantees and component interoperability in generated diagram artifacts.**

The `tt-a1i/archify` repository implements a contract-backed design system that governs how diagrams are rendered, validated, and delivered. Understanding Archify quality profiles and engineering contracts is essential for teams that require reproducible, high-fidelity SVG artifacts with strict composition standards.

## What Are Archify Quality Profiles?

Archify defines **quality profiles** as named configuration sets that determine how rendered diagrams are validated and what visual constraints they must satisfy. These profiles are selected via the CLI flag `--quality standard|showcase` and are reflected in the **composition receipt** attached to each SVG artifact.

### The Standard Profile

The `standard` profile applies the default set of validation rules, providing balanced rendering suitable for most development workflows. When no `--quality` flag is specified, Archify automatically selects this profile.

### The Showcase Profile

The `showcase` profile enforces a stricter **composition-quality contract** derived from the Fireworks Tech Graph. According to [`archify/references/composition-quality-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/composition-quality-contract.md), this profile guarantees zero line-crossings, no bridges, limited bends (maximum 2), and tighter spacing constraints (node spacing ≥32px, container gutter ≥16px).

## Core Engineering Contracts

Beyond profiles, Archify establishes **engineering contracts** that formalize expectations between components, tools, and generated artifacts. These contracts ensure consistent validation rules and schema versions across the ecosystem.

### Delivery Contract

Defined in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), the **Delivery Contract** specifies the schema for the composition receipt, the artifact checker, and required fields for each diagram including version, revision, and quality profile.

### Authoring Contract

The **Authoring Contract** governs how diagram authoring modules expose their SemVer, field definitions, timestamps, and source URLs. This ensures consistent package metadata across different authoring tools, as detailed in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).

### Composition-Quality Contract

As implemented in [`archify/references/composition-quality-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/composition-quality-contract.md), this contract outlines the visual quality metrics that the `showcase` profile must satisfy. The contract mandates specific pixel-based spacing requirements and topological constraints that the renderer must observe.

### Cross-Renderer Contracts

Unified contracts for sequence, lifecycle, dataflow, and workflow renderers guarantee consistent validation rules across all renderer types. These shared contracts are documented in [`archify/renderers/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/README.md) and ensure that schema versions remain synchronized regardless of output format.

## Working with Quality Profiles and Validation

You can specify quality profiles during rendering and validate outputs against their declared contracts using the Archify CLI.

Render with the default standard profile:

```bash
archify render diagram.json --output diagram.svg

```

Render with the stricter showcase profile:

```bash
archify render diagram.json --quality showcase --output diagram-showcase.svg

```

Validate a rendered diagram against its declared contract:

```bash
archify validate diagram-showcase.svg --quality showcase

```

When using the `showcase` profile, Archify generates a composition receipt embedded in the SVG metadata. The receipt follows the schema defined in the delivery contract:

```json
{
  "schemaVersion": "1.2",
  "revision": "a1b2c3d",
  "qualityProfile": "showcase",
  "checks": {
    "zeroCrossings": true,
    "noBridges": true,
    "maxBends": 2,
    "nodeSpacing": "≥32px",
    "containerGutter": "≥16px"
  },
  "status": "PASS"
}

```

## Summary

- Archify provides two **quality profiles**: `standard` for default rendering and `showcase` for strict visual guarantees.
- The `showcase` profile enforces zero line-crossings, no bridges, and specific spacing constraints as defined in [`archify/references/composition-quality-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/composition-quality-contract.md).
- **Engineering contracts** formalize expectations through the Delivery, Authoring, and Cross-Renderer contracts documented in the `archify/references/` directory.
- Use `--quality showcase` to opt into stricter validation and generate composition receipts that verify visual compliance against the defined contracts.

## Frequently Asked Questions

### What is the difference between standard and showcase profiles in Archify?

The `standard` profile applies default validation rules suitable for general development, while the `showcase` profile enforces strict visual guarantees including zero line-crossings, no bridges, and limited bends as specified in [`archify/references/composition-quality-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/composition-quality-contract.md). The showcase profile is designed for presentations and production documentation where visual polish is critical.

### How do I validate a diagram against its declared contract?

Use the `archify validate` command with the `--quality` flag matching your rendering profile, such as `archify validate diagram-showcase.svg --quality showcase`. This verifies compliance against the composition receipt schema defined in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md) and checks that all visual constraints are satisfied.

### Where are the contract definitions documented?

Contract definitions reside in the `archify/references/` directory, specifically [`delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/delivery-contract.md) for receipt schemas, [`authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/authoring-contract.md) for package metadata requirements, and [`composition-quality-contract.md`](https://github.com/tt-a1i/archify/blob/main/composition-quality-contract.md) for visual quality metrics. Additional renderer-specific contracts are documented in [`archify/renderers/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/README.md).

### Can I create custom quality profiles?

Currently, Archify supports only the built-in `standard` and `showcase` profiles as documented in the repository's [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md). While the contract system is designed to be extensible, implementing custom quality profiles requires modifications to the core validation engine and contract schema definitions.