Archify Architecture Diagram JSON Schema Structure: Complete Reference Guide

The Archify architecture diagram JSON schema is a strict, typed JSON IR defined in architecture.schema.json that enforces schema_version: 1, diagram_type: "architecture", and requires meta and components properties while optionally accepting layout, boundaries, connections, and cards.

Archify renders SVG-based architecture diagrams from deterministic JSON documents. The architecture diagram JSON schema governs exactly how you structure these documents to ensure the renderer produces consistent, validated output. This guide walks through every top-level property, its constraints, and its role in the rendering pipeline based on the source code in tt-a1i/archify.

---

Core Schema Requirements

Every valid architecture diagram must declare two fixed values at the root level. According to archify/schemas/architecture.schema.json, the top-level object requires:

Property	Value	Purpose
schema_version	1 (integer, const)	Schema version lock for forward compatibility
diagram_type	"architecture" (string, const)	Discriminator for the multi-format renderer

The schema sets "additionalProperties": false, rejecting any unrecognized keys. This guarantees that validated documents render identically across Archify versions.

---

The meta Object: Diagram Metadata

The meta property (defined in architecture.schema.json lines 11–66) captures all presentation and behavioral settings for the diagram.

Required and Optional Fields

Field	Required	Type/Values	Description
title	yes	non-empty string	Main heading displayed above the diagram
subtitle	no	string	Secondary descriptive line
output	no	string (path)	Target HTML file for rendered output
animation	no	"trace" | "none"	SVG load animation style
visual_preset	no	"classic" | "signal-flow" | "blueprint" | "editorial"	Pre-defined color palette and node shapes
quality_profile	no	"standard" | "showcase"	Validation strictness and visual polish level
engineering_profile	no	"deployment-ownership"	Engineering-specific view modes
repository	no	{url, revision} object	Git commit linkage (GitHub URL pattern, 40-char SHA-1)
views	no	guided view array	Focused subsets of components (re-used from common.schema.json)
legend	no	{mode, entries} object	Legend visibility and custom labels
viewBox	no	[width, height] array (≥ 320×240)	Explicit SVG canvas dimensions

The legend.mode accepts "auto", "compact", or "hidden" to control whether type labels appear below the diagram.

---

The layout Object: Grid Placement Control

When you need deterministic positioning, the optional layout property configures an explicit grid system:

{
  "layout": {
    "mode": "grid",
    "origin": [0, 0],
    "cols": 8,
    "gapX": 20,
    "gapY": 20,
    "cellW": 120,
    "cellH": 80
  }
}

Property	Constraints	Default Behavior
mode	"grid" only (required when layout present)	—
origin	[x, y] point array	Top-left grid corner
cols	integer 1–12	Column count for component placement
gapX, gapY	non-negative numbers	Inter-cell spacing in pixels
cellW	minimum 40	Minimum cell width
cellH	minimum 24	Minimum cell height

Omit layout entirely to let Archify's automatic layout engine compute positions based on connectivity and component types.

---

The components Array: Diagram Nodes

The components array (lines 82–127 in architecture.schema.json) defines every node in your architecture. Each component is a strictly-shaped object:

{
  "id": "api-gateway",
  "type": "backend",
  "label": "API Gateway",
  "sublabel": "v2.4.1",
  "tag": "nginx",
  "row": 1,
  "col": 3,
  "sources": [
    {"path": "src/gateway/main.go", "line": 1, "end_line": 150, "label": "entrypoint"}
  ]
}

Component Properties

Property	Required	Type/Constraints
id	yes	/^[a-zA-Z][a-zA-Z0-9_-]*$/ — must start with letter
type	yes	componentType enum from common.schema.json: frontend, backend, database, cloud, security, messagebus, external
label	yes	non-empty display name
sublabel	no	secondary text below label
tag	no	arbitrary short string (often version)
brand	no	string (≤2048 chars) or {url, sha256} object for logo
sources	no	array of 0–3 source locations with path, optional line/end_line, optional label
row, col	no	zero-based grid coordinates
pos	no	[x, y] point overriding grid placement
size	no	[width, height] positive dimensions

The type field drives visual styling—each componentType maps to distinct colors, icons, and node shapes in the renderer.

---

The boundaries Array: Visual Grouping

Boundaries wrap components into logical regions or security zones. Defined in lines 128–145 of the schema:

{
  "boundaries": [
    {
      "kind": "region",
      "label": "AWS us-east-1",
      "wraps": ["api-gateway", "auth-service", "user-db"],
      "pad": 16
    },
    {
      "kind": "security-group",
      "label": "DMZ",
      "wraps": ["api-gateway"]
    }
  ]
}

Property	Required	Description
kind	yes	"region" (geographic/cloud grouping) or "security-group" (trust boundary)
label	yes	displayed inside the boundary rectangle
wraps	yes	array of component ids (minimum 1)
pad	no	extra padding in pixels around wrapped items

Boundary kind determines stroke color and dash pattern—"region" uses solid lines while "security-group" applies security-themed styling.

---

The connections Array: Directed Relationships

Edges link components with rich routing and styling control (lines 146–171):

{
  "connections": [
    {
      "from": "api-gateway",
      "to": "auth-service",
      "label": "JWT verify",
      "variant": "security",
      "route": "orthogonal-h",
      "fromSide": "right",
      "toSide": "left",
      "width": 2.5
    }
  ]
}

Edge Properties

Property	Required	Type/Values
from	yes	source component id
to	yes	target component id
id	no	edge identifier (re-uses common.schema.json id pattern)
label	no	text rendered along the edge
variant	no	"default" | "emphasis" | "security" | "dashed"
fromSide, toSide	no	"left" | "right" | "top" | "bottom"
route	no	"auto" | "straight" | "orthogonal-h" | "orthogonal-v"
via	no	array of {x, y} points for forced bends
width	no	minimum 0.5 — SVG stroke width

Label positioning accepts labelAt (0.0–1.0 along path), labelDx/labelDy (offset pixels), and labelSegment (which segment of multi-segment routes).

---

The cards Array: Narrative Sidebars

Cards attach explanatory content beside the diagram, re-using definitions from common.schema.json:

{
  "cards": [
    {
      "dot": "emerald",
      "title": "Data Flow",
      "items": [
        "All requests flow through API Gateway",
        "Authentication enforced at edge",
        "Database connections use TLS 1.3"
      ]
    }
  ]
}

Property	Required	Constraints
dot	yes	color: cyan, emerald, violet, amber, rose, orange, slate
title	yes	non-empty string
items	yes	array of bullet point strings

Cards render as dismissible panels with colored bullets, useful for architectural decision records (ADRs), security notes, or operational runbooks.

---

Complete Valid Example

This minimal architecture diagram validates against architecture.schema.json and renders a three-tier web service:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "E-Commerce Platform",
    "subtitle": "Production deployment",
    "visual_preset": "signal-flow",
    "legend": {"mode": "auto"},
    "viewBox": [800, 400]
  },
  "layout": {
    "mode": "grid",
    "cols": 6,
    "gapX": 24,
    "gapY": 32,
    "cellW": 140,
    "cellH": 100
  },
  "components": [
    {"id": "cdn", "type": "cloud", "label": "CloudFront", "col": 0, "row": 0},
    {"id": "web", "type": "frontend", "label": "Next.js", "col": 2, "row": 0},
    {"id": "api", "type": "backend", "label": "API", "col": 3, "row": 1},
    {"id": "cache", "type": "database", "label": "Redis", "col": 5, "row": 0},
    {"id": "postgres", "type": "database", "label": "PostgreSQL", "col": 5, "row": 1}
  ],
  "boundaries": [
    {"kind": "region", "label": "AWS", "wraps": ["cdn", "web", "api", "cache", "postgres"]}
  ],
  "connections": [
    {"from": "cdn", "to": "web", "route": "orthogonal-h"},
    {"from": "web", "to": "api", "variant": "emphasis"},
    {"from": "api", "to": "cache", "variant": "dashed"},
    {"from": "api", "to": "postgres", "variant": "security"}
  ],
  "cards": [
    {
      "dot": "cyan",
      "title": "Architecture Notes",
      "items": ["Read-heavy workload", "Cache-aside pattern", "Encrypted at rest"]
    }
  ]
}

For a production-scale reference, see examples/archify-repo.architecture.json in the repository.

---

Schema Validation and CI Integration

The Archify CLI uses AJV to validate documents against architecture.schema.json. A typical CI pipeline:

1. Lint JSON syntax
2. Validate schema conformance: archify validate diagram.architecture.json
3. Render to HTML: archify build diagram.architecture.json --output docs/
4. Assert fixture parity: compare against archify/test/fixtures/v1-baseline/web-app.architecture.json

Because the schema permits no extra properties and fixes version constants, validated diagrams produce byte-identical renders across Archify patch versions.

---

Key Source Files

Path	Purpose
archify/schemas/architecture.schema.json	Master schema governing architecture diagrams
archify/schemas/common.schema.json	Shared $ref definitions: id, point, componentType, cards, legends
examples/archify-repo.architecture.json	Full-featured example with all sections populated
archify/test/fixtures/v1-baseline/web-app.architecture.json	CI regression test fixture

---

Summary

• Archify architecture diagram JSON schema requires schema_version: 1, diagram_type: "architecture", and a meta object with at minimum a title
• Components are typed nodes (frontend, backend, database, cloud, security, messagebus, external) with mandatory id and label
• Boundaries group components by kind: "region" or "security-group" with mandatory wraps array
• Connections link from → to component IDs with optional routing, styling, and label positioning
• Cards attach narrative content with colored bullets alongside the rendered SVG
• Strict additionalProperties: false ensures schema conformance guarantees render reproducibility

---

Frequently Asked Questions

What happens if I omit the layout property?

Archify falls back to its automatic layout engine, computing positions based on connectivity patterns and component types. Grid coordinates in components are ignored when layout is absent.

Can I reference external logo images in components?

Yes. The brand property accepts either a plain URL string (≤2048 characters) or an object with url and sha256 for integrity verification: {"url": "https://cdn.example.com/logo.svg", "sha256": "abc123..."}.

How do I link a diagram to a specific Git commit?

Use the meta.repository object with url matching GitHub's pattern and a 40-character revision SHA-1. This enables the renderer to generate permalinks and "view source" buttons in the output HTML.

Why does schema validation reject my file with valid-looking JSON?

The architecture.schema.json enforces additionalProperties: false at the root and on most nested objects. Typos in property names, extra fields, or incorrect types (e.g., string "1" instead of integer 1 for schema_version) will fail validation.

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