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

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 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. 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:

{
  "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 with reusable types in 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, 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 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, while the rendering implementation that consumes these structures is located at archify/renderers/architecture/render-architecture.mjs.

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