What Are Archify Engineering Profiles and How to Use Deployment-Ownership Validation

Archify engineering profiles are schema-validated extensions that enforce strict engineering-truth constraints on Architecture diagrams, with deployment-ownership being the only current profile that validates owner assignments, region boundaries, and security requirements.

In the tt-a1i/archify repository, engineering profiles provide an opt-in mechanism for "fail-closed deployment review." When enabled, they transform Archify from a flexible diagramming tool into a rigorous validation system for production infrastructure documentation.

Understanding Engineering Profiles in Archify

An engineering profile is an optional property defined in a diagram's meta object. The Architecture schema declares this as engineering_profile with a strict enum constraint—currently permitting only one value.

According to archify/schemas/architecture.schema.json (line 22), the schema defines:

"engineering_profile": {
  "enum": ["deployment-ownership"]
}

When this property is absent (the default), Archify skips all profile-specific validations. Diagrams may omit owners, regions, and crossing mechanisms without triggering errors. This default behavior supports exploratory or high-level architectural sketches where precision is not yet required.

When explicitly set to deployment-ownership, the system activates strict validation mode in the shared renderer.

The Deployment-Ownership Profile Explained

The deployment-ownership profile enforces five core engineering-truth constraints on Architecture diagrams:

1. Mandatory ownership — Every non-external component must declare an explicit owner.
2. Single region assignment — Each workload belongs to exactly one region.
3. Boundary declarations — Region and security-group boundaries must be explicitly stated.
4. Private database placement — All databases must be private and reside within a shared region.
5. Crossing mechanism labels — Any connection traversing region or security-group boundaries must specify a real crossing mechanism.

These rules are implemented in archify/renderers/shared/engineering-profiles.mjs. The profile constant is defined at line 3:

const DEPLOYMENT_PROFILE = 'deployment-ownership';

The renderer activates validation at line 150 after confirming both the diagram type (architecture) and the profile match:

// Conceptual flow from engineering-profiles.mjs line 150
if (diagram.meta.engineering_profile === DEPLOYMENT_PROFILE) {
  // Apply deployment-ownership validation rules
}

How to Enable and Validate Deployment-Ownership

Step 1: Add the Profile to Your Architecture File

Create or modify your .architecture.json file to include the engineering_profile property in meta:

{
  "meta": {
    "title": "Production Deployment",
    "engineering_profile": "deployment-ownership"
  },
  "components": [
    {
      "id": "api-gateway",
      "type": "workload",
      "owner": "platform-team",
      "region": "us-east-1"
    },
    {
      "id": "primary-db",
      "type": "database",
      "owner": "data-team",
      "region": "us-east-1",
      "network": "private"
    }
  ],
  "connections": [
    {
      "from": "api-gateway",
      "to": "primary-db",
      "crossing": "vpc-peering"
    }
  ]
}

This example follows the pattern in archify/examples/production-deployment.architecture.json (line 11), which demonstrates a valid deployment-ownership configuration.

Step 2: Validate with Archify CLI

Run the validation command to check compliance:

archify validate --json production-deployment.architecture.json

A passing validation returns a receipt with the profile name and empty diagnostics:

{
  "engineeringProfile": "deployment-ownership",
  "diagnostics": [],
  "valid": true
}

Validation failures include specific diagnostic messages indicating which constraint was violated—missing owner, unassigned region, unlabeled crossing, or public database placement.

Step 3: Generate Validated Artifacts

Use the deliver command to produce validated outputs:

archify deliver --json production-deployment.architecture.json

The generated SVG embeds a machine-readable attribute as seen in docs/gallery/artifacts/production-deployment.architecture.html (line 4547):

<svg data-engineering-profile="deployment-ownership" ...>

This attribute allows automated systems to verify that a diagram passed deployment-ownership validation before inclusion in documentation or deployment pipelines.

Validation Receipts and Machine-Readable Proofs

The deployment-ownership profile creates an auditable trail through validation receipts. These receipts serve two purposes:

• Human review — The JSON output shows explicit confirmation that all engineering-truth constraints were satisfied.
• Automated gates — CI/CD pipelines can parse engineeringProfile and diagnostics fields to enforce documentation quality.

The test suite in archify/test/engineering-profile.test.mjs confirms this behavior, ensuring that valid diagrams receive clean receipts while violations produce actionable diagnostic messages.

When to Use Deployment-Ownership

Apply the deployment-ownership profile when your Architecture diagrams must serve as authoritative documentation for:

• Production infrastructure reviews — Where missing ownership or region information would block deployment.
• Compliance audits — Where proof of boundary controls and private data placement is required.
• Cross-team coordination — Where explicit owner assignment prevents operational ambiguity.

Skip the profile for early-stage designs, proof-of-concept diagrams, or any context where strict validation would impede iteration speed.

Key Source Files and Their Roles

File	Purpose
archify/schemas/architecture.schema.json	Declares the engineering_profile enum and validates input structure.
archify/renderers/shared/engineering-profiles.mjs	Implements runtime validation logic for deployment-ownership.
archify/examples/production-deployment.architecture.json	Reference implementation showing correct profile usage.
archify/test/engineering-profile.test.mjs	Automated tests for validation behavior and receipt format.
docs/deployment-ownership-profile-acceptance-2026-07-23.md	Acceptance criteria documenting profile requirements.
docs/gallery/artifacts/production-deployment.architecture.html	Published proof showing embedded SVG profile attribute.

Summary

• Engineering profiles are opt-in, schema-validated extensions that tighten Archify's Architecture diagram semantics.
• deployment-ownership is the sole available profile, enforcing owner assignment, single-region workloads, boundary declarations, private databases, and labeled crossings.
• Enable the profile by setting "engineering_profile": "deployment-ownership" in your diagram's meta object.
• Validation receipts and SVG attributes provide machine-readable proof of compliance.
• The implementation spans schema definition, shared renderer logic, example files, and comprehensive tests in tt-a1i/archify.

Frequently Asked Questions

What happens if I omit the engineering_profile property?

Archify operates in default mode with no additional constraints. Diagrams validate successfully without owners, regions, or crossing mechanisms. This supports flexible sketching but provides no engineering-truth guarantees.

Can I create custom engineering profiles?

No. The schema enum in architecture.schema.json restricts engineering_profile to "deployment-ownership". Profile extension would require modifying the schema and adding corresponding validation logic to engineering-profiles.mjs.

How does deployment-ownership validation differ from standard Archify validation?

Standard validation ensures structural integrity—valid component types, required fields, and connection endpoints. Deployment-ownership adds semantic constraints: business logic rules about ownership, security boundaries, and operational correctness that standard validation ignores.

Where can I see a validated deployment-ownership diagram?

The gallery artifact at docs/gallery/artifacts/production-deployment.architecture.html contains a published SVG with data-engineering-profile="deployment-ownership". The source input appears in archify/examples/production-deployment.architecture.json.

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