# Archify Core Data Model Explained: JSON Intermediate Representation Deep Dive

> Explore Archify's core data model, a typed JSON Intermediate Representation (IR) that structures system maps with schemas, metadata, components, and connections. Learn how Archify organizes data for your projects.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-05

---

**Archify's core data model is a typed JSON "Intermediate Representation" (IR) where system maps are structured as validated JSON documents with `schema_version`, `meta` metadata, `components` nodes, `connections` edges, and optional `boundaries`, `layout`, and `cards` sections.**

The **Archify core data model** standardizes how architecture diagrams, workflows, sequences, data flows, and lifecycle charts are defined. Rather than proprietary binary formats, Archify uses human-readable JSON governed by strict JSON Schema definitions. This article breaks down the exact structure, validation rules, and source locations in the `tt-a1i/archify` repository.

## Architecture Diagram Structure

Every Architecture diagram in Archify follows a consistent top-level schema defined in [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). The six primary properties are:

| Property | Required | Purpose |
|----------|----------|---------|
| `schema_version` | Yes | Fixed integer `1` — schema compatibility marker |
| `diagram_type` | Yes | Must be `"architecture"` for this diagram type |
| `meta` | Yes | Human-readable metadata (title, locale, visual preset, guided views) |
| `components` | Yes | **Array of nodes** — the building blocks of your system |
| `connections` | No | **Edges** linking components by `id` references |
| `boundaries` | No | **Logical groups** that visually cluster components |
| `layout` | No | **Grid positioning** (mode, origin, columns, cell dimensions) |
| `cards` | No | **Side-panel annotations** for detailed component documentation |

Shared constraints — including valid `id` patterns and enumerated component types — live in [[`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json).

## Components: The Node Model

The `components` array is the heart of the Archify core data model. Each component is a JSON object with the following structure:

```json
{
  "id": "api_gateway",
  "type": "backend",
  "label": "API Gateway",
  "sub_label": "NGINX",
  "row": 1,
  "col": 2,
  "pos": "center",
  "width": 2,
  "height": 1,
  "branding": {
    "icon": "server",
    "color": "#3b82f6"
  },
  "sources": [
    {
      "file": "infra/nginx.conf",
      "line": 15,
      "url": "https://github.com/org/repo/blob/main/infra/nginx.conf#L15"
    }
  ]
}

```

**Required fields:** `id`, `type`, `label`.  
**Positioning:** `row`, `col`, and `pos` control grid placement.  
**Sizing:** `width` and `height` are measured in grid cells.  
**Provenance:** The optional `sources` array links components to actual source code.

**Valid component types** are strictly enumerated in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json):

- `frontend`
- `backend`
- `database`
- `cloud`
- `security`
- `messagebus`
- `external`

All `id` values must match the regex `^[a-zA-Z][a-zA-Z0-9_-]*$` — starting with a letter, followed by letters, digits, underscores, or hyphens.

## Connections: The Edge Model

Relationships between components are defined in the optional `connections` array. Each connection specifies directed edges with rich visual control:

```json
{
  "from": "web",
  "to": "api",
  "label": "HTTPS",
  "variant": "bidirectional",
  "fromPin": "bottom",
  "toPin": "top",
  "routing": "ortho",
  "via": [
    {"x": 100, "y": 200},
    {"x": 100, "y": 300}
  ],
  "width": 2
}

```

**Key properties:**
- `from` and `to` reference component `id`s
- `variant` controls line style (`default`, `bidirectional`, `dashed`)
- `fromPin`/`toPin` specify attachment sides (`top`, `bottom`, `left`, `right`)
- `routing` chooses path algorithm (`direct`, `ortho` for orthogonal)
- `via` array defines intermediate waypoints as `{x, y}` objects

## Boundaries and Visual Grouping

The optional `boundaries` property creates logical containers — security groups, deployment zones, or architectural layers:

```json
{
  "boundaries": [
    {
      "id": "public_zone",
      "label": "Public DMZ",
      "componentIds": ["web", "cdn"],
      "padding": 20
    },
    {
      "id": "private_zone",
      "label": "Internal Services",
      "componentIds": ["api", "worker"],
      "padding": 16
    }
  ]
}

```

Boundaries wrap existing components by `id` reference and add visual padding in pixels. They do not create new nodes — they are purely presentational groupings.

## Layout and Grid System

Positioning defaults can be overridden via the optional `layout` object:

```json
{
  "layout": {
    "mode": "grid",
    "origin": "top-left",
    "cols": 4,
    "gapX": 24,
    "gapY": 24,
    "cellW": 120,
    "cellH": 80
  }
}

```

**Layout modes:**
- `grid` (default) — strict row/column positioning
- `free` — absolute coordinates

When `mode` is `grid`, `row` and `col` in components are required. The `cellW` and `cellH` define base unit sizes; `gapX`/`gapY` add spacing between cells.

## Cards: Side-Panel Documentation

The `cards` array attaches rich documentation panels to components:

```json
{
  "cards": [
    {
      "id": "db_details",
      "title": "Database Configuration",
      "componentIds": ["db_primary", "db_replica"],
      "content": "PostgreSQL 15 with read replicas in us-east-1 and eu-west-1"
    }
  ]
}

```

Cards appear in side panels during rendering and support markdown content for deeper technical context.

## Minimal Valid Example

The smallest Architecture diagram that passes validation requires only four fields:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Minimal System"
  },
  "components": [
    {
      "id": "single",
      "type": "backend",
      "label": "Service"
    }
  ]
}

```

This validates against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) but renders as a single unconnected node. Real-world diagrams add connections, boundaries, and layout for meaningful visualization.

## JSON Schema Validation Pipeline

Archify validates every diagram before rendering. The validation pipeline guarantees:

1. **Structural compliance** — required fields present, correct types
2. **Identifier uniqueness** — no duplicate `id` values across components, boundaries, or cards
3. **Reference integrity** — `from`/`to` in connections and `componentIds` in boundaries/cards must exist
4. **Enumeration constraints** — `type`, `variant`, `routing`, and other enums match allowed values
5. **Pattern matching** — all `id`s conform to `^[a-zA-Z][a-zA-Z0-9_-]*$`

Validation failures return deterministic error receipts with JSON Path pointers to offending properties, enabling automated correction workflows.

## Source File Locations

| File Path | Description |
|-----------|-------------|
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Complete Architecture diagram schema |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Shared definitions across all diagram types |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Workflow diagram extensions |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Sequence diagram extensions |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Data-flow diagram extensions |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | Lifecycle diagram extensions |
| [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) | Simple three-tier example |
| [`archify/examples/checkout-platform.base.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/checkout-platform.base.architecture.json) | Complex example with boundaries and cards |

## Summary

- **Archify's core data model** is a typed JSON Intermediate Representation validated by JSON Schema
- **Five diagram types** share common definitions in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and extend type-specific schemas
- **Seven component types** (`frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`) define node semantics
- **Grid-based layout** with optional free positioning controls visual organization
- **Source-code provenance** via `sources` arrays bridges diagrams to implementation
- **Machine-readable validation** ensures model correctness before any rendering occurs

## Frequently Asked Questions

### What makes Archify's data model different from Diagrams-as-Code tools like Mermaid?

Archify uses a **structured, schema-validated JSON IR** rather than text-based DSLs. This enables programmatic generation, strict validation with deterministic error messages, and first-class source-code provenance linking. As implemented in `tt-a1i/archify`, the JSON format integrates directly with build pipelines and code analysis tools.

### Can I extend the Archify core data model with custom component types?

No — component types are **strictly enumerated** in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) to ensure consistent visual rendering and semantic understanding. The allowed values are `["frontend","backend","database","cloud","security","messagebus","external"]`. For specialized needs, use the `sub_label` field or `cards` for additional context rather than inventing new types.

### How does Archify handle large systems with hundreds of components?

The **grid layout system** scales through `layout.cols` configuration and component `row`/`col` positioning. The `boundaries` feature creates logical groupings, and `guided_views` in `meta` support progressive disclosure — showing subsets of components for different audiences. Large examples like [`checkout-platform.base.architecture.json`](https://github.com/tt-a1i/archify/blob/main/checkout-platform.base.architecture.json) demonstrate these patterns.

### Is the Archify JSON format stable across versions?

The `schema_version` field (currently fixed at `1`) provides explicit versioning. As defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), this integer signals compatibility. Future schema changes will increment this version, and the validation pipeline will reject documents with unsupported versions.