Archify's Quality Profiles and Validation Rules: Standard vs Showcase

Archify defines two quality profiles—standard (permissive) and showcase (strict)—that determine validation rules ranging from basic JSON schema compliance to rigorous visual-quality budgets including zero line crossings and bend limits.

Archify is an open-source diagramming framework from the tt-a1i/archify repository that validates and renders technical diagrams through JSON-based specifications. The quality profiles and their validation rules serve as the gatekeeper between rough architectural drafts and production-ready visualizations, determining which geometric and structural constraints apply during the rendering pipeline.

What Are Archify's Quality Profiles?

Archify defines exactly two named quality profiles that influence how diagrams are validated and rendered:

• standard: The default permissive profile that allows typical visual layouts while enforcing basic structural correctness.
• showcase: A strict "polished-delivery" profile designed for production-ready visualizations that must meet rigorous visual-quality budgets.

These profiles are stored in the meta.quality_profile field of every diagram document and are validated against JSON Schema enums in schema definition files.

Validation Rules by Profile

The validation logic differs significantly depending on which profile is active.

Standard Profile Validation

When meta.quality_profile is set to "standard", Archify applies lenient validation rules focused primarily on structural integrity. The validation ensures the diagram conforms to the JSON schema with required fields and proper IDs, but imposes no strict visual-quality budgets. This profile is ideal for rapid prototyping and iterative design where geometric perfection is not required.

Showcase Profile Validation

The showcase profile triggers additional visual-quality constraints implemented in archify/renderers/shared/geometry.mjs. According to the research notes in docs/research-visual-evolution-round-4.md, this profile enforces:

• Zero line crossings: No connecting lines may intersect.
• No bridge edges: Edge bridging is prohibited.
• At most two bends per edge: Connector paths are limited to two directional changes.
• Minimum node spacing and container gutter rules: Strict padding requirements between elements.

The design rationale states: "The showcase profile budgets zero line crossings, no bridges, at most two bends, minimum node spacing, and container gutters. Its fallback is to simplify or split the topology."

Schema Definition and Code Implementation

The quality profiles are formally defined in the JSON Schema specifications for each diagram type. In files such as archify/schemas/architecture.schema.json, archify/schemas/workflow.schema.json, and archify/schemas/sequence.schema.json, the field is constrained as:

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

This ensures that only the two recognized profile values are accepted during validation. When the showcase profile is selected, the renderer's geometry module executes stricter validation logic that checks for the visual budgets described above, while the standard profile bypasses these geometric constraints.

Practical Usage Examples

You can specify the quality profile in your diagram's metadata or through the CLI validation tool.

To configure a workflow diagram for strict showcase quality:

const workflow = {
  schema_version: 1,
  diagram_type: "workflow",
  meta: {
    title: "Order Processing",
    quality_profile: "showcase",   // Enforce strict visual quality
    visual_preset: "classic",
    animation: "trace"
  },
  lanes: [{ id: "lane-1", label: "Customer" }],
  nodes: [/* … */],
  edges: [/* … */]
};

For quick prototypes using the permissive standard profile:

const arch = {
  schema_version: 1,
  diagram_type: "architecture",
  meta: {
    title: "Microservice Architecture",
    quality_profile: "standard",   // Permissive validation
    visual_preset: "signal-flow"
  },
  components: [/* … */],
  connections: [/* … */]
};

To validate a diagram via CLI with the showcase profile:

archify validate workflow path/to/diagram.json --quality showcase --json

Testing the Validation Rules

The test suite in archify/test/layout-rules.test.mjs exercises the profile-specific validation logic by constructing diagrams with both meta.quality_profile: "standard" and "showcase" settings. These tests verify the appropriate pass/fail outcomes for geometric constraints, ensuring that showcase diagrams fail validation when they contain line crossings or excessive edge bends, while standard diagrams tolerate these visual imperfections.

Summary

• Archify provides two quality profiles: standard (lenient) and showcase (strict).
• The standard profile validates JSON schema compliance without enforcing visual geometry rules.
• The showcase profile requires zero line crossings, no bridge edges, maximum two bends per edge, and strict spacing rules.
• Profile selection occurs via the meta.quality_profile field, constrained by schema enums in files like architecture.schema.json and workflow.schema.json.
• The geometry validation logic resides in archify/renderers/shared/geometry.mjs.
• CLI validation supports --quality showcase for command-line checking of visual constraints.

Frequently Asked Questions

What happens if I don't specify a quality profile in my Archify diagram?

If you omit the quality_profile field, Archify defaults to the standard profile. This applies basic JSON schema validation for required fields and proper IDs but does not enforce the strict visual-quality budgets required by the showcase profile.

Can I switch between quality profiles without changing my diagram's structure?

Yes, you can toggle between standard and showcase by modifying only the meta.quality_profile value. However, switching to showcase may cause validation failures if your existing diagram contains line crossings, bridge edges, or excessive bends that violate the stricter geometric constraints defined in the source code.

Which Archify diagram types support quality profiles?

All diagram types support quality profiles, including architecture, workflow, lifecycle, sequence, and dataflow diagrams. Each schema file—such as architecture.schema.json, workflow.schema.json, and sequence.schema.json—contains the same quality_profile enum definition, ensuring consistent validation behavior across diagram types.

How does the showcase profile handle validation failures?

When the showcase profile detects violations such as line crossings or excessive bends, the validation fails and the renderer may attempt to simplify or split the topology automatically. If automatic correction is not possible, you must manually adjust the diagram layout to meet the visual-quality budgets documented in docs/research-visual-evolution-round-4.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}