# Structural Arrays in Archify’s Architecture Schema: A Complete Reference

> Explore Archify's architecture schema, detailing the four structural arrays: components, boundaries, connections, and cards. Understand how these arrays model your architecture diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-10

---

**Archify defines four core structural arrays—`components`, `boundaries`, `connections`, and `cards`—that together model the nodes, zones, edges, and annotations of an architecture diagram.**

The open-source Archify project provides a JSON-based schema for describing system architecture diagrams as structured data. According to the source code in `tt-a1i/archify`, the **architecture schema** uses four distinct structural arrays to represent every visual and logical element of a diagram, from individual microservices to security boundaries and data flow connections.

## The Four Structural Arrays Defined in Archify

The schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) organizes diagram data into four top-level arrays. Each array serves a specific purpose in the visual representation of your system.

### components (Required)

The **`components`** array lists individual runtime elements that appear as nodes in the diagram. These include services, databases, UI elements, and other infrastructure pieces.

According to the source code, this array is mandatory and defined at lines 85–130 of the schema file. Each component requires an `id`, `type`, `label`, and positioning coordinates (`row` and `col`).

### boundaries (Optional)

The **`boundaries`** array groups components into logical or security zones such as *regions* or *security‑groups*. This optional array (lines 131–148) wraps related components visually, indicating trust boundaries or deployment zones.

### connections (Optional)

The **`connections`** array describes directed edges between components, including routing information, labels, and visual styling. Found at lines 149–175, this array defines how data flows through your architecture using `from` and `to` references that match component IDs.

### cards (Optional)

The **`cards`** array provides optional annotation panels that attach to components or connections to convey additional metadata. Located at line 176, cards support extra documentation without cluttering the main diagram elements.

## Schema Implementation Details

The architecture schema relies on reusable definitions stored in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This file contains shared types like `componentType`, `id`, and `point` that the four structural arrays reference for consistency.

When you invoke `archify render architecture <file>.json`, the renderer located at `archify/renderers/architecture/render-architecture.mjs` consumes these arrays to generate SVG or HTML output. The renderer validates that the `components` array exists, then optionally processes `boundaries`, `connections`, and `cards` to build the complete visual representation.

## Complete Architecture JSON Example

Below is a minimal, valid architecture definition that demonstrates all four structural arrays in practice:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Simple Web Service"
  },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Web UI", "row": 0, "col": 0 },
    { "id": "backend",  "type": "backend",  "label": "API Service", "row": 1, "col": 0 },
    { "id": "db",       "type": "database", "label": "PostgreSQL",   "row": 2, "col": 0 }
  ],
  "boundaries": [
    {
      "kind": "region",
      "label": "Public Cloud",
      "wraps": ["frontend", "backend"]
    },
    {
      "kind": "security-group",
      "label": "Data Zone",
      "wraps": ["db"]
    }
  ],
  "connections": [
    { "from": "frontend", "to": "backend", "label": "HTTPS", "route": "auto" },
    { "from": "backend",  "to": "db",      "label": "SQL",  "route": "auto" }
  ],
  "cards": [
    {
      "id": "card1",
      "title": "Important Note",
      "content": "All traffic passes through the API gateway."
    }
  ]
}

```

This example creates three nodes grouped into two security boundaries, connected by two labeled edges, with one annotation card attached to the diagram.

## Summary

- **Four structural arrays** define Archify architecture diagrams: `components`, `boundaries`, `connections`, and `cards`.
- Only the `components` array is required; the other three are optional.
- The schema is defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) with reusable types in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json).
- The renderer at `archify/renderers/architecture/render-architecture.mjs` processes these arrays to generate visual output.
- Each array uses specific line ranges in the schema file (components: 85–130, boundaries: 131–148, connections: 149–175, cards: 176).

## Frequently Asked Questions

### What is the purpose of the components array in Archify?

The `components` array serves as the foundational node list for every architecture diagram. It defines individual runtime elements such as databases, microservices, and user interfaces with unique identifiers and grid positions. According to the source code at lines 85–130 of [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), this array is the only required structural element, as it provides the essential nodes that other arrays reference.

### Are boundaries required when defining an architecture schema?

No, the `boundaries` array is optional. You can create valid architecture diagrams without grouping components into logical zones. However, when used, boundaries visually wrap related components to indicate security groups, deployment regions, or other logical partitions. The schema defines this array at lines 131–148 as an optional top-level property.

### How do connections define routing between components?

The `connections` array creates directed edges between components using `from` and `to` properties that reference component IDs. Each connection supports additional metadata including labels (e.g., "HTTPS"), routing instructions (`route: "auto"`), and styling options. Located at lines 149–175 of the schema, this array transforms isolated nodes into a connected system architecture.

### Where is the architecture schema defined in the Archify source code?

The primary schema definition resides in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) in the `tt-a1i/archify` repository. This file contains the formal JSON Schema definitions for all four structural arrays. Supporting type definitions live in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), while the rendering implementation that consumes these structures is located at `archify/renderers/architecture/render-architecture.mjs`.