What Are Archify Engineering Profiles and Deployment-Ownership? A Complete Guide

Archify engineering profiles are optional, schema-validated extensions that enforce strict engineering-truth constraints on Architecture diagrams, with deployment-ownership being the first available profile that mandates explicit component owners, regional boundaries, and crossing mechanisms for production-ready documentation.

Archify, the open-source architecture-as-code tool from tt-a1i/archify, introduces engineering profiles to bridge the gap between informal diagrams and deployable infrastructure documentation. These profiles allow teams to opt into rigorous validation rules that ensure diagrams accurately reflect ownership and deployment reality.

Understanding Archify Engineering Profiles

An engineering profile is defined in the Architecture schema as an optional property located at meta.engineering_profile. When present, the profile activates a strict validation mode in the Archify loader that goes beyond standard syntax checking to enforce semantic constraints.

According to the source code in archify/schemas/architecture.schema.json (line 22), the engineering_profile field accepts an enum with a single validated value: "deployment-ownership". This design allows the system to support additional profiles in the future while maintaining backward compatibility.

If the profile is absent—the default behavior—Archify skips the additional checks, permitting diagrams that do not specify owners, regions, or boundary mechanisms. The profile is strictly opt-in, activated only when a user requests a "fail-closed deployment review."

The Deployment-Ownership Profile Explained

Schema Definition and Constants

The deployment-ownership profile is formally declared in archify/schemas/architecture.schema.json, where line 22 defines the enum containing this single allowed value. At runtime, the shared renderer references this value through a constant defined at the top of archify/renderers/shared/engineering-profiles.mjs (line 3):

const DEPLOYMENT_PROFILE = 'deployment-ownership';

Validation Rules and Constraints

When the loader detects "engineering_profile": "deployment-ownership" in the diagram metadata, it activates validation logic implemented around line 150 in engineering-profiles.mjs. This logic enforces five specific engineering-truth constraints:

• Explicit ownership: Every non-external component must declare an explicit owner.
• Regional affinity: Each workload must belong to exactly one region.
• Boundary declarations: Region and security-group boundaries must be explicitly declared.
• Database privacy: All databases must be private and reside inside a shared region.
• Crossing mechanisms: Any connection that changes region or security-group membership must be labelled with a real crossing mechanism.

Implementation Details

The renderer checks that the diagram type is architecture and that the profile constant matches the value in meta.engineering_profile before applying these extra validations. This guard logic prevents the constraints from running on incompatible diagram types.

How to Enable Deployment-Ownership in Your Architecture

To activate the profile, add the engineering_profile key to your diagram's metadata block:

{
  "meta": {
    "title": "Production Deployment",
    "engineering_profile": "deployment-ownership"
  },
  "components": [
    {
      "id": "api-service",
      "type": "workload",
      "owner": "platform-team",
      "region": "us-east-1"
    }
  ]
}

Validate the diagram with the profile enforced using the CLI:

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

A successful validation returns a receipt containing the profile name:

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

Output Artifacts and Machine-Readable Evidence

When validation passes, Archify embeds proof of the profile into multiple output artifacts. The JSON receipt from archify validate --json or archify deliver --json includes the field engineeringProfile: "deployment-ownership", as verified in the test suite located at archify/test/engineering-profile.test.mjs.

Additionally, the generated SVG artifact carries a machine-readable attribute. In docs/gallery/artifacts/production-deployment.architecture.html (line 4547), the SVG element includes:

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

This attribute allows downstream tooling to programmatically verify that a diagram was validated against the deployment-ownership constraints.

Summary

• Archify engineering profiles are schema-driven extensions defined in meta.engineering_profile that tighten diagram semantics for specific use cases.
• The deployment-ownership profile is the first available implementation, enforcing rules about component ownership, regional boundaries, and connection mechanisms.
• Implementation resides in archify/renderers/shared/engineering-profiles.mjs, with the constant defined at line 3 and validation logic at line 150.
• Activation requires setting "engineering_profile": "deployment-ownership" in the diagram metadata, as shown in archify/examples/production-deployment.architecture.json.
• Successful validation produces machine-readable evidence in both JSON receipts and SVG data-engineering-profile attributes.

Frequently Asked Questions

What happens if I don't specify an engineering profile?

If the engineering_profile property is absent from your diagram metadata, Archify operates in default mode and skips the strict validation rules. Your diagram will not be required to declare owners, regions, or crossing mechanisms, allowing greater flexibility for early-stage design work.

Can I create custom engineering profiles beyond deployment-ownership?

Currently, the schema in archify/schemas/architecture.schema.json defines an enum with only one allowed value: "deployment-ownership". While the architecture supports future profiles, the codebase does not yet expose APIs for defining custom user profiles outside of the core repository.

How does the deployment-ownership profile affect the SVG output?

When the profile is active and validation succeeds, the renderer injects a data-engineering-profile="deployment-ownership" attribute into the root SVG element. This is visible in the gallery artifacts and allows CI/CD pipelines to verify that a diagram meets deployment-ownership standards by inspecting the generated HTML or SVG files.

Where can I find working examples of the deployment-ownership profile?

The repository includes a complete example at archify/examples/production-deployment.architecture.json, which demonstrates the correct metadata structure and component definitions required to pass validation. The test suite in archify/test/engineering-profile.test.mjs provides additional examples of valid and invalid configurations for reference.

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