# How to Use Archify for Dataflow Diagrams: A Complete Guide to JSON-Driven Pipeline Visualizations

> Master Archify for dataflow diagrams. Learn to generate interactive visualizations from JSON IR in three simple stages. Get your complete guide now.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-07

---

**Archify generates deterministic, interactive dataflow diagrams from a single typed JSON source through three stages: describe your pipeline, compose the JSON IR, and render to self-contained HTML.**

Dataflow diagrams in Archify follow a structured workflow that separates data definition from presentation. The `tt-a1i/archify` repository provides a schema-driven renderer that transforms pipeline descriptions into interactive visualizations without hand-drawing or diagram tools.

## Why Use Archify for Dataflow Diagrams

Traditional diagram tools require manual layout and suffer from drift between code and documentation. Archify solves this by using a **typed JSON intermediate representation (IR)** as the single source of truth. The [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) enforces structure, enabling deterministic rendering and version-controlled diagrams that stay synchronized with your architecture.

The approach suits teams using agent-assisted workflows—Archify-enabled agents in Cursor, Claude Code, Codex CLI, or OpenCode can generate valid JSON from natural language descriptions.

## Three Stages to Create a Dataflow Diagram

### Stage 1: Describe Your Data Pipeline

Prompt an Archify-enabled agent with the keyword **dataflow** to activate the dataflow renderer. Include stage names, component types, and data boundaries in your description.

Example prompt:

```

Use Archify to draw a dataflow diagram for our event-collection pipeline:
Browser → Edge collector → Consent gate → Event Stream → Warehouse → Dashboard.
Show the PII boundary and the batch aggregation path.

```

The agent references [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) to select the correct diagram type and schema. This contract file defines how agents map intent to renderer selection.

### Stage 2: Compose the JSON IR

The agent outputs a JSON file conforming to [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json). The schema requires these top-level fields:

- `schema_version` — Must be `1`
- `diagram_type` — Fixed to `"dataflow"`
- `meta` — `title`, optional `subtitle`, `viewBox`, `animation`, `visual_preset`, `quality_profile`
- `stages` — Ordered lifecycle stages (e.g., Sources, Ingest, Process, Store, Consume)
- `nodes` — Components with `id`, `type`, `label`, stage index, row index, layout hints
- `flows` — Directed edges with `from`, `to`, `label`, `variant` styling, routing hints
- `cards` — Optional summary panels rendered as clickable dots

The `type` field drives icon selection: `frontend`, `cloud`, `security`, `database`, `backend`, `messagebus`, etc. The `variant` field in flows controls visual styling: `emphasis`, `security`, `dashed`, `default`.

### Stage 3: Render to Interactive HTML

Run the CLI renderer located at `archify/renderers/dataflow/render-dataflow.mjs`:

```bash
node archify/renderers/dataflow/render-dataflow.mjs <input>.dataflow.json <output>.html

```

Omitting the output argument falls back to `meta.output` or defaults to [`dataflow.html`](https://github.com/tt-a1i/archify/blob/main/dataflow.html) in the current directory—behavior documented in [`archify/renderers/dataflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/README.md).

The output is a self-contained HTML file with no external dependencies. It supports:

- Theme toggling (dark/light)
- Animated trace playback (`meta.animation: "trace"`)
- Guided views (`meta.views` with `focus` arrays)
- Legend entries (`meta.legend`)
- PNG export at 1200×630 for share cards

## Complete Dataflow Diagram Example

This minimal but complete example generates a product analytics pipeline visualization. Save as [`product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/product-analytics.dataflow.json):

```json
{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": {
    "title": "Product Analytics Data Flow",
    "subtitle": "Events → Edge API → Consent → Stream → Warehouse → Dashboard",
    "viewBox": [1080, 760],
    "animation": "trace",
    "quality_profile": "showcase",
    "views": [
      { "id": "collection", "label": "Collection path", "focus": ["web","mobile","edge","stream"] }
    ]
  },
  "stages": [
    { "label": "Sources" },
    { "label": "Ingest" },
    { "label": "Process" },
    { "label": "Store" },
    { "label": "Consume" }
  ],
  "nodes": [
    { "id": "web",      "type": "frontend", "label": "Web App",       "stage": 0, "row": 0 },
    { "id": "mobile",   "type": "frontend", "label": "Mobile",        "stage": 0, "row": 2 },
    { "id": "edge",     "type": "cloud",    "label": "Edge API",      "stage": 1, "row": 1 },
    { "id": "consent",  "type": "security", "label": "Consent Gate",  "stage": 2, "row": 0 },
    { "id": "stream",   "type": "messagebus","label": "Event Stream","stage": 2, "row": 2 },
    { "id": "warehouse","type": "database", "label": "Warehouse",      "stage": 3, "row": 2 },
    { "id": "dashboard","type": "backend",  "label": "Dashboards",    "stage": 4, "row": 1 }
  ],
  "flows": [
    { "id": "web-edge",    "from": "web",    "to": "edge",    "label": "clickstream", "variant": "emphasis", "fromSide": "right", "toSide": "left" },
    { "id": "edge-consent","from": "edge",   "to": "consent","label": "identity+consent", "variant": "security", "fromSide": "top",    "toSide": "left" },
    { "id": "consent-stream","from":"consent","to":"stream","label":"accepted events","variant":"emphasis","fromSide":"right","toSide":"left" },
    { "id": "stream-warehouse","from":"stream","to":"warehouse","label":"normalized facts","variant":"emphasis","route":"straight"},
    { "id": "warehouse-dashboard","from":"warehouse","to":"dashboard","label":"metrics SQL","variant":"default"}
  ],
  "cards": [
    {
      "dot": "emerald",
      "title": "Primary Data Path",
      "items": ["Events flow left→right through all stages", "Labels name data assets"]
    }
  ]
}

```

Render and view:

```bash
node archify/renderers/dataflow/render-dataflow.mjs product-analytics.dataflow.json product-analytics.html

```

Open [`product-analytics.html`](https://github.com/tt-a1i/archify/blob/main/product-analytics.html) in any browser. The diagram shows data flowing left-to-right across five stages, with security boundaries highlighted and animation tracing the primary path.

## Key Configuration Options

### Animation and Quality

| Setting | Effect |
|---------|--------|
| `meta.animation: "trace"` | Plays progressive reveal of data flow |
| `meta.quality_profile: "showcase"` | Highest fidelity rendering |
| `meta.visual_preset: "enterprise"` | Predefined color/icon theme |

### Routing Hints

Flows accept `fromSide`, `toSide` (top, right, bottom, left) and `route` (straight, orthogonal) to control edge geometry. The `via` array accepts intermediate coordinates for precise path control.

### Guided Views

Define `meta.views` with `id`, `label`, and `focus` arrays to create presentation bookmarks. Each view zooms and highlights specified node IDs.

## Core Source Files

- [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) — JSON Schema validation
- `archify/renderers/dataflow/render-dataflow.mjs` — CLI renderer implementation
- [`archify/examples/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/product-analytics.dataflow.json) — Reference implementation
- [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) — Agent contract for diagram type selection

## Summary

- Archify dataflow diagrams use **JSON IR as source of truth**—no manual drawing required
- Include **"dataflow" keyword** in agent prompts to activate the correct renderer
- Structure diagrams with `stages`, `nodes`, `flows`, and optional `cards`
- Render via `render-dataflow.mjs` to produce **self-contained HTML** with theme, animation, and export features
- All topology derives from authored JSON—no inferred or invented connections

## Frequently Asked Questions

### What is the minimum JSON required for a valid dataflow diagram?

A valid diagram requires `schema_version: 1`, `diagram_type: "dataflow"`, at least one stage, one node, and one flow connecting two nodes. The `meta.title` field is recommended but not enforced by schema. Omitting optional fields produces a functional but plain diagram.

### Can I use Archify dataflow diagrams without an AI agent?

Yes. Write JSON manually or generate it programmatically, then run `render-dataflow.mjs` directly. The agent integration in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) is optional—it's designed for convenience, not requirement.

### How do I customize colors and icons in my dataflow diagram?

Colors derive from `node.type` (frontend, cloud, security, etc.) and `flow.variant` (emphasis, security, dashed). For deeper customization, modify `meta.visual_preset` or post-process the generated SVG. The renderer does not expose direct color hex fields in the JSON schema.

### Why does my rendered diagram look different in dark mode?

The HTML viewer auto-detects system preference and applies theme variables. Explicitly set `meta.theme: "light"` or `"dark"` to override. Theme assets are embedded—no external CSS fetches occur.