How to Configure Boundaries for Grouping Components in Archify Diagrams

Archify lets you visually group related components by defining a boundaries array in your diagram's JSON source, where each boundary specifies a kind (region, security-group, etc.), a label, and a wraps array containing the component IDs to enclose.

Archify, an open-source diagramming tool maintained in the tt-a1i/archify repository, uses a declarative JSON format to render architecture diagrams. When you need to logically group components—whether by deployment region, network security perimeter, or trust zone—you configure boundaries to create visual overlays that help viewers understand ownership and relationships at a glance.

Understanding the Boundaries Schema

According to the authoring contract in archify/references/authoring-contract.md, boundaries are defined in a top-level boundaries array within your diagram JSON. Each boundary object acts as a visual container that wraps specified components without altering their underlying relationships.

Required Fields

Every boundary definition must include three core fields:

• kind: The semantic classification of the boundary. Valid values include region, security-group, trust, and availability-zone.
• label: The human-readable text displayed on the boundary border, such as "AWS us-east-1 / production".
• wraps: An array of strings containing the component IDs that the boundary should enclose. These IDs must match entries defined in the components section of the same file.

Optional Configuration

You can fine-tune the visual presentation using the optional pad field. This integer value specifies extra padding in pixels around the wrapped components, allowing you to expand the boundary box beyond the default margin when components appear too crowded.

How Boundaries Render

The Archify renderer processes boundaries as translucent overlay boxes that automatically expand to fit the positioned components listed in the wraps array. Unlike relationships or connections, boundaries do not represent data flow; they provide visual distinction to indicate grouping by ownership, trust, process, or deployment scope. The renderer calculates the bounding box based on component pos values and applies any specified pad value to determine the final border size.

Common Boundary Types

Choose the appropriate kind value based on your architectural concern:

• region: Indicates geographic deployment zones, such as specific cloud regions or data centers.
• security-group: Highlights network perimeters and private application networks that isolate back-end services.
• trust: Separates external actors (like customers) from internal services to emphasize security boundaries.
• availability-zone: Shows resilience boundaries within a single region.

Configuration Example

Below is a complete boundary configuration taken from archify/examples/production-deployment.architecture.json. This example groups infrastructure into an AWS region boundary, then applies a narrower security-group boundary to internal workloads only:

{
  "boundaries": [
    {
      "kind": "region",
      "label": "AWS us-east-1 / production",
      "wraps": ["edge", "gateway", "api_a", "api_b", "redis", "postgres", "events", "worker", "audit"]
    },
    {
      "kind": "security-group",
      "label": "private application network",
      "wraps": ["api_a", "api_b", "redis", "postgres", "events", "worker"]
    }
  ]
}

Notice that api_a, api_b, and other internal services appear in both boundaries, demonstrating that components can belong to multiple overlapping groups.

Best Practices for Boundary Design

When configuring boundaries in Architecture mode, follow these constraints to maintain diagram clarity:

1. Limit component counts: Keep the number of primary components between 6–12 to prevent visual overload.
2. Scope boundaries logically: Restrict boundaries to real ownership, trust, process, or deployment scopes rather than arbitrary groupings.
3. Use padding sparingly: Add pad values only when the default margin fails to separate the boundary line from component icons.
4. Validate component IDs: Ensure every ID in the wraps array exists in the components section to prevent rendering errors.

Summary

• Archify diagrams use a top-level boundaries array to visually group components.
• Each boundary requires kind, label, and wraps fields, with an optional pad parameter for spacing.
• Valid kind values include region, security-group, trust, and availability-zone.
• The renderer auto-sizes boundaries around positioned components; boundaries serve as visual overlays, not relationship definitions.
• Reference archify/references/authoring-contract.md and archify/schemas/README.md for complete schema details.

Frequently Asked Questions

What is the boundaries array in Archify?

The boundaries array is a top-level property in Archify diagram JSON files that contains objects defining visual containers for grouping components. Each boundary specifies which components to wrap and how to label the resulting region, creating overlays that indicate ownership, security zones, or deployment regions without affecting the underlying component relationships.

How do I add padding around a boundary?

Add the optional pad field to your boundary object, setting it to an integer representing pixels. For example, "pad": 14 expands the boundary box by 14 pixels beyond the default margin calculated from the wrapped components' positions.

Can a component belong to multiple boundaries?

Yes. A single component ID can appear in the wraps array of multiple boundaries simultaneously. This is useful when a service belongs to both a geographic region and a specific security group, as shown in the production deployment example where internal APIs appear in both the region and security-group boundaries.

Where is the authoritative schema for boundary definitions?

The authoritative schema is documented in archify/references/authoring-contract.md, which defines all valid fields for boundary objects. Additionally, archify/schemas/README.md provides the formal JSON schema reference for all diagram types, including complete specifications for the boundaries array structure.

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