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

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:

{
  "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 — a web clickstream pipeline with multiple transformation stages
• Rendered output: 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 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.

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