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

> Discover the two structural arrays, nodes and flows, Archify uses to represent data flow diagrams in its intermediate representation. Learn how Archify builds DFDs.

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

---

**Archify uses exactly two top-level JSON arrays—`nodes` and `flows`**—to represent every data flow diagram in its intermediate representation (IR).

Archify, an open-source visualization toolkit developed by tt-a1i, adopts a deliberately minimal approach to modeling data pipelines. Rather than complex graph structures or proprietary formats, the tool stores all diagram semantics in two flat arrays. This design choice keeps the schema extensible while remaining trivial to generate from scripts, databases, or manual JSON authoring.

## The Two Core Arrays: `nodes` and `flows`

Every data flow diagram IR in Archify contains these mandatory top-level keys:

| Array | Purpose | Typical Fields |
|-------|---------|--------------|
| **`nodes`** | Entities that **produce, transform, or consume** data | `id`, `type`, `label`, `position` (x/y), `colour`, `icon` |
| **`flows`** | **Directed edges** carrying data between nodes | `source`, `target`, `label`, `colour`, `style` |

These arrays are processed sequentially by the renderer at `archify/renderers/dataflow/render-dataflow.mjs`. The renderer does not require additional metadata structures—it computes layout, draws connectors, and generates final SVG/HTML output directly from these two collections.

## Minimal Data Flow Diagram Example

The following JSON demonstrates the complete IR structure required by Archify:

```json
{
  "diagram_type": "dataflow",
  "nodes": [
    { "id": "clicks",      "type": "source",    "label": "Web Clicks",       "x": 0, "y": 0 },
    { "id": "filter",      "type": "transform", "label": "Filter Spam",      "x": 200, "y": 0 },
    { "id": "analytics",   "type": "sink",      "label": "Analytics Store",  "x": 400, "y": 0 }
  ],
  "flows": [
    { "source": "clicks",   "target": "filter",   "label": "raw events" },
    { "source": "filter",   "target": "analytics","label": "cleaned events" }
  ]
}

```

Key observations from the Archify source code:

- **`id`** values in `nodes` must be unique strings—they serve as foreign keys for the `flows` array
- **`source`** and **`target`** in each flow object must reference existing node `id` values
- Positional coordinates (`x`, `y`) are optional but recommended; the renderer applies automatic layout when absent

## Real-World Reference: Product Analytics Pipeline

The repository includes a fully worked example demonstrating production-grade usage of these structural arrays:

- **Source IR:** [`docs/gallery/sources/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json) — a web clickstream pipeline with multiple transformation stages
- **Rendered output:** [`docs/gallery/artifacts/product-analytics.dataflow.html`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/product-analytics.dataflow.html) — interactive HTML generated from the same two arrays

This example reveals how Archify encodes complex pipeline logic without expanding beyond the `nodes`/`flows` duality. Additional visual properties (colours, icons, annotations) attach directly to individual objects rather than requiring separate structures.

## Why Two Arrays Suffice

Archify's data flow representation intentionally avoids the complexity common in graph exchange formats. According to the implementation in `archify/renderers/dataflow/render-dataflow.mjs`, this constraint provides three advantages:

1. **Trivial serialization** — any programming language can produce valid JSON with two arrays
2. **Predictable rendering** — the renderer traverses fixed structure rather than recursive schemas
3. **Clean extension** — new node types, flow styles, or metadata fields add without schema migration

## Summary

- Archify data flow diagrams rely on **exactly two structural arrays**: `nodes` and `flows`
- The `nodes` array describes **entities**; the `flows` array describes **connections** between them
- All visual and semantic properties embed as object fields—no separate metadata structures required
- The renderer at `archify/renderers/dataflow/render-dataflow.mjs` processes these arrays directly to produce SVG/HTML output
- Repository examples at [`docs/gallery/sources/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json) demonstrate production usage

## Frequently Asked Questions

### What fields are required in the `nodes` array?

Each node object must include an **`id`** (unique string) and **`type`** (e.g., `source`, `transform`, `sink`). Fields like `label`, `x`, `y`, and `colour` are optional—the renderer applies defaults when omitted.

### Can a data flow diagram contain disconnected nodes?

Yes. The `flows` array may be empty or omit references to certain node IDs. Disconnected nodes render as isolated elements without incoming or outgoing edges. The renderer does not enforce graph connectivity.

### Where does Archify validate the JSON structure?

Validation occurs within `archify/renderers/dataflow/render-dataflow.mjs` at runtime. The renderer checks that all `source` and `target` values in `flows` correspond to existing node `id` values, throwing descriptive errors for dangling references.

### How do I convert the IR to a viewable diagram?

Pass the JSON file to the Archify CLI or load it programmatically through the renderer module. The renderer outputs static HTML/SVG files suitable for embedding in documentation or web applications—no runtime server required.