Key Schema Arrays for Each Archify Diagram Type: The Complete Reference

Archify defines five diagram families—Architecture, Workflow, Sequence, Dataflow, and Lifecycle—each exposing specific top-level array properties in their JSON Schema files that hold the diagram’s structural elements.

The tt-a1i/archify repository validates diagram definitions using strict JSON Schema files located in the archify/schemas/ directory. Understanding the key schema arrays for each Archify diagram type allows you to author valid diagram JSON files that render correctly across the five supported families. These top-level arrays act as entry points where you populate objects that satisfy the referenced component-type definitions.

Architecture Diagram Schema Arrays

The Architecture diagram type uses archify/schemas/architecture.schema.json to validate system structure diagrams. This schema exposes four primary array properties that define visual boxes, containment regions, and connectivity.

• components – The visual boxes representing system parts (frontend, backend, database, cloud, security, messagebus, external).
• boundaries – Optional region or security-group wrappers that visually group components.
• connections – Links between component IDs that form the edges of the diagram.
• cards – Optional overlay cards attached to the diagram for additional metadata.

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Sample Architecture" },
  "components": [
    { "id": "ui",   "type": "frontend",   "label": "UI" },
    { "id": "api",  "type": "backend",    "label": "API" },
    { "id": "db",   "type": "database",   "label": "DB" }
  ],
  "connections": [
    { "from": "ui",  "to": "api",  "variant": "default" },
    { "from": "api", "to": "db",   "variant": "default" }
  ]
}

Workflow Diagram Schema Arrays

Workflow diagrams in archify/schemas/workflow.schema.json support complex pipeline visualization with eight distinct array properties. These arrays control horizontal lanes, execution phases, grouping constructs, and semantic validation rules.

• lanes – Horizontal tracks that group nodes (for example, "dev" or "ci").
• phases – Optional higher-level bands spanning columns across lanes.
• groups – Named boxes that span a specific lane and column range.
• nodes – Individual boxes representing steps (frontend, backend, cloud, etc.).
• edges – Directed connections between node IDs.
• cards – Optional overlay cards for metadata.
• mainPath – An ordered list of node IDs defining the primary execution path.
• semanticChecks – Rules including allowedRoots, allowedTerminals, requiredEdges, and requiredPaths.

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "CI Pipeline" },
  "lanes": [{ "id": "dev", "label": "Dev" }],
  "nodes": [
    { "id": "checkout", "lane": "dev", "col": 0, "type": "frontend", "label": "Checkout" },
    { "id": "build",    "lane": "dev", "col": 1, "type": "backend",  "label": "Build" }
  ],
  "edges": [
    { "from": "checkout", "to": "build", "role": "main" }
  ]
}

Sequence Diagram Schema Arrays

Sequence diagrams use archify/schemas/sequence.schema.json to model interactions over time. The schema defines five array properties that manage lifelines, messages, and activation bars.

• participants – The lifelines representing actors (frontend, backend, external, etc.).
• messages – Arrows between participants including optional variant and note properties.
• segments – Optional horizontal separator lines that divide the diagram.
• activations – Vertical activation bars linked to specific participants.
• cards – Optional overlay cards attached to the diagram.

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Client‑Server Interaction" },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client" },
    { "id": "server", "type": "backend",  "label": "Server" }
  ],
  "messages": [
    { "from": "client", "to": "server", "y": 200, "label": "GET /data" },
    { "from": "server", "to": "client", "y": 300, "label": "200 OK" }
  ]
}

Dataflow Diagram Schema Arrays

Dataflow diagrams in archify/schemas/dataflow.schema.json model data transformation pipelines using four primary arrays. These define processing stages, the nodes within those stages, and the flow between them.

• stages – Ordered processing steps, each with an ID, label, and optional type.
• nodes – Individual boxes living inside a stage (frontend, backend, database, cloud, security, messagebus, external).
• edges – Directed connections between node IDs with optional variant, route, and routing helpers.
• cards – Optional overlay cards for additional context.

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "ETL Pipeline" },
  "stages": [
    { "id": "extract", "label": "Extract" },
    { "id": "transform", "label": "Transform" },
    { "id": "load", "label": "Load" }
  ],
  "nodes": [
    { "id": "src", "stage": "extract", "type": "external", "label": "Source DB" },
    { "id": "proc", "stage": "transform", "type": "backend", "label": "Processor" },
    { "id": "dest", "stage": "load", "type": "database", "label": "Warehouse" }
  ],
  "edges": [
    { "from": "src", "to": "proc" },
    { "from": "proc", "to": "dest" }
  ]
}

Lifecycle Diagram Schema Arrays

The Lifecycle diagram type defined in archify/schemas/lifecycle.schema.json models state machines with three core array properties. These arrays capture states, transitions between them, and optional metadata overlays.

• states – Nodes representing lifecycle states (start, active, success, error, etc.).
• transitions – Directed edges connecting states with optional variant, role, and routing hints.
• cards – Optional overlay cards for additional diagram information.

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "states": [
    { "id": "queued",   "type": "start",    "label": "Queued" },
    { "id": "running",  "type": "active",   "label": "Running" },
    { "id": "finished", "type": "success",  "label": "Finished" }
  ],
  "transitions": [
    { "from": "queued",   "to": "running",  "variant": "default" },
    { "from": "running",  "to": "finished", "variant": "default" }
  ]
}

Summary

The key schema arrays for each Archify diagram type serve as the structural foundation for all visual representations in the tt-a1i/archify repository.

• Architecture diagrams rely on components, boundaries, connections, and cards.
• Workflow diagrams utilize eight arrays including lanes, nodes, edges, mainPath, and semanticChecks.
• Sequence diagrams use participants, messages, segments, activations, and cards.
• Dataflow diagrams structure data pipelines through stages, nodes, edges, and cards.
• Lifecycle diagrams model state machines using states, transitions, and cards.

Populating these top-level arrays with properly typed objects ensures your diagram JSON validates against the corresponding schema files.

Frequently Asked Questions

What is the difference between components and nodes in Archify schemas?

components appear exclusively in Architecture diagrams within archify/schemas/architecture.schema.json to represent high-level system parts like databases and services. nodes appear in Workflow, Dataflow, and other diagram types to represent individual steps or processing units within lanes or stages. While both define visual boxes, components connect via connections while nodes use edges.

Which schema array defines the execution order in Workflow diagrams?

The mainPath array in archify/schemas/workflow.schema.json defines the ordered list of node IDs that constitute the primary execution path through the workflow. This array works alongside the edges array to determine both the visual layout and logical flow of the diagram.

How do I add overlay information to any Archify diagram type?

Every Archify diagram schema includes a cards array that accepts overlay card objects. These cards attach metadata to the diagram without affecting the primary structural layout. You can populate the cards array in Architecture, Workflow, Sequence, Dataflow, and Lifecycle diagrams to provide additional context.

Are boundaries required in Architecture diagrams?

No, the boundaries array in archify/schemas/architecture.schema.json is optional. Boundaries serve as visual wrappers or security-group regions around components, but valid Architecture diagrams require only the components array and optionally connections. Omit boundaries when your diagram does not require logical containment groups.

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