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

> Discover the four main structural arrays stages nodes flows and cards that define data flow diagrams in Archify for machine readable JSON graphs.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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."

```json
"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.

```json
"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`](https://github.com/tt-a1i/archify/blob/main/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.

```json
"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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/event-stream.dataflow.json) demonstrates routing directives and anchor specifications:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/product-analytics.dataflow.json)** — Production-ready example demonstrating standard usage of `stages`, `nodes`, and `flows`.
- **[`archify/examples/event-stream.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/event-stream.dataflow.json)** — Advanced example showcasing optional flow properties including routing and side anchors.
- **[`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.