# How to Configure Boundaries for Grouping Components in Archify Diagrams

> Learn to configure boundaries for grouping components in Archify diagrams. Visually organize your architecture by defining kinds, labels, and wrapping components with the boundaries array.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) and [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), which defines all valid fields for boundary objects. Additionally, [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) provides the formal JSON schema reference for all diagram types, including complete specifications for the `boundaries` array structure.