Archify Core Data Model Explained: JSON Intermediate Representation Deep Dive

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

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:

{
  "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:

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

{
  "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 ids
• 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:

{
  "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:

{
  "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:

{
  "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:

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

This validates against 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 ids 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	Complete Architecture diagram schema
archify/schemas/common.schema.json	Shared definitions across all diagram types
archify/schemas/workflow.schema.json	Workflow diagram extensions
archify/schemas/sequence.schema.json	Sequence diagram extensions
archify/schemas/dataflow.schema.json	Data-flow diagram extensions
archify/schemas/lifecycle.schema.json	Lifecycle diagram extensions
archify/examples/web-app.architecture.json	Simple three-tier example
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 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 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 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, this integer signals compatibility. Future schema changes will increment this version, and the validation pipeline will reject documents with unsupported versions.

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