What Are the Main Structural Arrays for Data Flow Diagrams in Archify?

Archify defines data flow diagrams using four primary structural arrays—stages, nodes, flows, and cards—that together form a complete machine-readable graph description in JSON format.

Archify is an open-source diagramming tool that renders architecture diagrams from structured JSON definitions. According to the dataflow.schema.json specification in the repository, every data flow diagram consists of specific top-level arrays that define the visual hierarchy, components, and connections. Understanding these arrays is essential for authoring valid diagram files that Archify can render into interactive HTML or SVG outputs.

The Four Core Structural Arrays

The schema at archify/schemas/dataflow.schema.json mandates four arrays that control different aspects of the diagram logic. Each array serves a distinct purpose in describing how data moves through your system.

Stages

The stages array defines an ordered list of logical layers used to group nodes vertically. Each stage object requires a label property that appears as the column or layer header in the rendered diagram.

In the schema source (lines 90-107), stages establish the horizontal or vertical framework that constrains where nodes can be placed. This creates the visual separation between system boundaries like "Source," "Processing," and "Sink."

"stages": [
  { "label": "Source" },
  { "label": "Processing" },
  { "label": "Sink" }
]

Nodes

The nodes array contains the individual system components—services, databases, queues, or external APIs—that appear as boxes in the diagram. According to lines 108-162 of the schema, every node must provide five required properties: id (unique identifier), type (component category), label (display text), stage (index matching the stages array), and row (vertical position within the stage).

Optional visual properties allow you to override default styling, such as colors, icons, or dimensions. The type field determines which icon set Archify applies to the rendered component.

"nodes": [
  { "id": "src", "type": "service", "label": "API", "stage": 0, "row": 0 },
  { "id": "proc", "type": "service", "label": "Worker", "stage": 1, "row": 0 },
  { "id": "db", "type": "database", "label": "DB", "stage": 2, "row": 0 }
]

Flows

The flows array specifies directed connections between nodes, mapping the actual data movement through your system. As defined in lines 163-238 of dataflow.schema.json, each flow requires three properties: from (source node ID), to (target node ID), and label (connection description).

Optional attributes include route (routing algorithm), fromSide and toSide (anchor points), and label positioning controls (labelAt, labelDx, labelDy). These properties give you granular control over how edges appear without affecting the logical connection.

"flows": [
  { "from": "src", "to": "proc", "label": "request" },
  { "from": "proc", "to": "db", "label": "store" }
]

Cards (Optional)

The cards array provides reusable UI snippets that attach to nodes or flows for enhanced documentation. Defined in the shared common.schema.json and referenced at lines 239-242 of the data flow schema, cards support rich text, code blocks, or hyperlinks that appear in interactive views or tooltips.

While optional, cards enable Archify to generate guided views and detailed legends without cluttering the core diagram structure.

Complete Minimal Example

The repository provides a reference implementation at archify/examples/product-analytics.dataflow.json demonstrating the required structure. A valid data flow diagram requires at minimum the stages, nodes, and flows arrays alongside schema metadata:

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Simple Data Flow" },
  "stages": [
    { "label": "Source" },
    { "label": "Processing" },
    { "label": "Sink" }
  ],
  "nodes": [
    { "id": "src", "type": "service", "label": "API", "stage": 0, "row": 0 },
    { "id": "proc", "type": "service", "label": "Worker", "stage": 1, "row": 0 },
    { "id": "db", "type": "database", "label": "DB", "stage": 2, "row": 0 }
  ],
  "flows": [
    { "from": "src", "to": "proc", "label": "request" },
    { "from": "proc", "to": "db", "label": "store" }
  ]
}

Advanced Flow Configuration

For diagrams requiring precise visual control, the schema supports extended flow properties. The example at archify/examples/event-stream.dataflow.json demonstrates routing directives and anchor specifications:

{
  "from": "src",
  "to": "proc",
  "label": "request",
  "route": "straight",
  "fromSide": "right",
  "toSide": "left",
  "labelAt": { "x": 50, "y": 30 },
  "labelDx": 10,
  "labelDy": -5
}

These properties control edge routing algorithms, specify which side of a node box connects to the flow, and微调 label positioning using coordinate offsets.

Key Source Files and Schema Locations

Understanding where Archify defines these arrays helps when extending or validating diagrams:

• archify/schemas/dataflow.schema.json — Contains the canonical JSON Schema defining the four structural arrays, their required properties, and validation rules.
• archify/examples/product-analytics.dataflow.json — Production-ready example demonstrating standard usage of stages, nodes, and flows.
• archify/examples/event-stream.dataflow.json — Advanced example showcasing optional flow properties including routing and side anchors.
• archify/package.json — Project metadata confirming "dataflow" as a supported diagram type within the Archify ecosystem.

Summary

• Archify data flow diagrams rely on four top-level arrays defined in dataflow.schema.json: stages, nodes, flows, and cards.
• The stages array creates logical layers, while nodes place components within those layers using stage and row indices.
• The flows array connects nodes directionally using from and to identifiers, with optional routing and positioning controls.
• Cards provide optional documentation attachments defined in the shared schema.
• All arrays work together to enable Archify to render interactive HTML and SVG outputs from declarative JSON definitions.

Frequently Asked Questions

What is the required schema version for Archify data flow diagrams?

Archify currently requires "schema_version": 1 as declared in the root of your JSON file. This version identifier ensures the parser validates your diagram against the correct specification in archify/schemas/dataflow.schema.json.

How do I define visual positioning for nodes in Archify?

Position nodes using the stage and row properties. The stage integer maps to the index of your stages array, while row controls vertical ordering within that stage. For example, "stage": 0, "row": 1 places the node in the first stage's second row.

Can I attach documentation cards to specific flows?

Yes. While the cards array is defined at the top level, individual card objects can reference specific flow IDs or node IDs to attach contextual documentation. Cards are defined in common.schema.json and referenced by the data flow schema at lines 239-242, enabling rich tooltips and guided views without affecting the core graph structure.

Where is the data flow schema defined in the Archify repository?

The authoritative schema resides at archify/schemas/dataflow.schema.json in the repository root. This file defines the exact structure, required fields, and validation rules for the stages, nodes, flows, and cards arrays, along with line-number references for specific property constraints.

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