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

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 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 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. 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:

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 in the current directory—behavior documented in 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:

{
  "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:

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

Open 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 — JSON Schema validation
• archify/renderers/dataflow/render-dataflow.mjs — CLI renderer implementation
• archify/examples/product-analytics.dataflow.json — Reference implementation
• 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 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.

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