# How Does the `meta.quality_profile` Setting Affect Archify Diagram Generation?

> Discover how the meta.quality_profile setting in Archify controls diagram generation, influencing rendering precision, styling, and export fidelity for your architecture diagrams.

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

---

**The `meta.quality_profile` setting in Archify controls which visual and layout preset is applied during diagram generation, determining rendering precision, styling richness, and export fidelity.**

Archify uses a **quality profile**—specified either via the `--quality` CLI flag or the `meta.quality_profile` field in your JSON input—to configure how much computational effort the engine invests in layout refinement and visual polish. This setting directly influences the trade-off between generation speed and output quality for architecture diagrams.

## What `meta.quality_profile` Configures

When you set a quality profile, Archify applies a predefined bundle of rendering parameters. The profile affects four primary dimensions:

- **Layout precision** – Stricter convergence criteria for the deterministic layout engine, yielding fewer overlapping edges and more balanced node spacing
- **Styling richness** – Enables shadows, gradients, and richer label typography that are stripped out in lower-quality modes
- **Animation behavior** – Some profiles activate animated tracing (`meta.animation = "trace"`), while others disable motion for static export
- **Export fidelity** – Determines resolution, format options (PNG, SVG, WebM), and whether share-card graphics are generated

## Setting Quality Profile via CLI

The most common way to specify a quality profile is through the `--quality` flag when invoking `archify.mjs`. This flag populates `meta.quality_profile` in the internal intermediate representation (IR).

```bash

# Generate a polished, presentation-ready diagram

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

# Use minimal quality for rapid iteration (default behavior)

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json

```

In the `archify/bin/archify.mjs` entry point, the `--quality` argument is parsed and injected into the document's metadata structure before validation and rendering occur.

## Setting Quality Profile in JSON Input

You can also embed the quality profile directly in your diagram specification. The `meta` object accepts `quality_profile` alongside other configuration keys like `locale`, `animation`, and `visual_preset`.

```json
{
  "meta": {
    "locale": "en",
    "visual_preset": "signal-flow",
    "animation": "trace",
    "quality_profile": "showcase"
  },
  "nodes": [
    { "id": "api-gateway", "type": "service", "label": "API Gateway" }
  ],
  "edges": [
    { "from": "client", "to": "api-gateway", "type": "request" }
  ]
}

```

## Available Quality Profiles

Archify recognizes profile names such as:

| Profile | Use Case | Characteristics |
|---------|----------|---------------|
| `showcase` | Presentations, documentation | Maximum layout refinement, full styling, animation enabled, high-resolution exports |
| `baseline` | Development, CI/CD pipelines | Fast rendering, minimal styling, static output, reduced resolution |

When `meta.quality_profile` is omitted, Archify defaults to a baseline-equivalent configuration prioritizing speed over polish.

## How Quality Profile Propagates Through the Pipeline

1. **CLI parsing** – `archify/bin/archify.mjs` extracts `--quality <profile>` and merges it into document metadata
2. **Schema validation** – The `meta` object is validated against [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json), which permits an optional `quality_profile` field
3. **IR construction** – The validated quality profile is embedded in the intermediate representation
4. **Layout engine** – The profile selects convergence thresholds and optimization passes for node positioning
5. **Render stage** – Visual features and export parameters are applied based on the active profile

## Performance Implications

Choosing a quality profile involves measurable trade-offs:

- **Showcase profiles** may increase generation time by 3–5× due to additional layout iterations and post-processing effects
- **Baseline profiles** complete in sub-second times for diagrams with fewer than 100 nodes
- **Memory usage** scales with profile quality due to larger offscreen buffers for shadow and gradient compositing

For iterative workflows, omit `--quality` or explicitly use `--quality baseline`. For final artifacts committed to documentation or shared with stakeholders, `--quality showcase` ensures maximum visual impact.

## Summary

- `meta.quality_profile` selects a bundled configuration of layout precision, styling, animation, and export parameters
- Set via `--quality <profile>` CLI flag or directly in JSON `meta` object
- `showcase` prioritizes visual fidelity at computational cost; `baseline` (default) prioritizes speed
- Defined in [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json), processed through `archify/bin/archify.mjs`
- Omission triggers default fast-rendering behavior suitable for development cycles

## Frequently Asked Questions

### What happens if I specify both `--quality` CLI flag and `meta.quality_profile` in my JSON?

The CLI flag takes precedence. Archify merges command-line arguments after parsing the input file, so explicitly passing `--quality showcase` will override any `quality_profile` value present in the source JSON.

### Can I define custom quality profiles beyond `showcase` and `baseline`?

The repository's schema structure in [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json) supports extensible profile names as strings. While the built-in engine recognizes standard profiles, you can pass arbitrary profile identifiers—the rendering pipeline will apply defaults for unrecognized profiles and log a warning.

### Does `quality_profile` affect validation strictness or only rendering?

The quality profile influences rendering and export only. Schema validation in Archify is deterministic and does not vary with quality settings. A diagram that validates under `baseline` will validate identically under `showcase`; only the generated visual output differs.