How to Create Data Flow Diagrams Using Archify: A Complete Guide

Archify converts plain-language descriptions or structured JSON intermediate representations into interactive data flow diagrams using the dataflow renderer.

Data flow diagrams (DFDs) in Archify visualize how data moves through stages, nodes, and components in a system. The tool supports both manual JSON authoring and AI-assisted generation from natural language descriptions. This guide explains the complete workflow, from installation to rendered output, based on the actual source code implementation.

Installing the Archify Skill

Before creating diagrams, install the Archify skill package that contains all renderers including the dataflow module:

npx -y skills add tt-a1i/archify --skill archify --agent codex --global --copy --yes

The skill registers the archify command globally and copies renderer files to your local environment. The installation logic appears in [docs/start.html](https://github.com/tt-a1i/archify/blob/main/docs/start.html), which provides the primary web interface for diagram creation.

Selecting the Data Flow Diagram Type

Archify supports multiple diagram types through a tabbed interface. To create a data flow diagram:

• Web UI: Click the Data Flow tab in [start.html](https://github.com/tt-a1i/archify/blob/main/docs/start.html) (HTML element with data-type="dataflow" at line 21)
• Gallery navigation: Browse to gallery.html?filter=dataflow to view existing data flow examples

The type selector switches the internal renderer to archify/renderers/dataflow/render-dataflow.mjs, which handles parsing and visualization logic specific to data flow semantics.

Providing Input: Two Approaches

Archify accepts either natural language descriptions or typed JSON intermediate representations (IR). Both ultimately resolve to the same JSON structure consumed by the renderer.

Natural Language Description Mode

Enter a concise description of your data pipeline in the descriptionPrompt field ([start.html](https://github.com/tt-a1i/archify/blob/main/docs/start.html), lines 62-66):

"User clicks a product page, the clickstream is sent to an event-stream processor, enriched with user metadata, then stored in a data warehouse."

The system transforms this into structured JSON IR automatically. This mode accelerates prototyping when exact node specifications aren't yet finalized.

Typed JSON IR Mode

For precise control, author a *.dataflow.json file following the data flow schema. The repository provides a canonical example at [docs/gallery/sources/product-analytics.dataflow.json](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json):

{
  "title": "Product Analytics Pipeline",
  "nodes": [
    {
      "id": "web-frontend",
      "label": "Web Frontend",
      "type": "external",
      "description": "User-facing web application"
    },
    {
      "id": "click-collector",
      "label": "Click Collector",
      "type": "service",
      "description": "Captures raw click events"
    },
    {
      "id": "stream-processor",
      "label": "Event Stream Processor",
      "type": "service",
      "description": "Enriches and filters events in real-time"
    },
    {
      "id": "data-warehouse",
      "label": "Analytics Warehouse",
      "type": "store",
      "description": "Columnar storage for analytical queries"
    }
  ],
  "flows": [
    {
      "from": "web-frontend",
      "to": "click-collector",
      "label": "click events",
      "data": "JSON payload with user_id, product_id, timestamp"
    },
    {
      "from": "click-collector",
      "to": "stream-processor",
      "label": "raw events",
      "data": "Avro-encoded event stream"
    },
    {
      "from": "stream-processor",
      "to": "data-warehouse",
      "label": "enriched events",
      "data": "Parquet files with derived dimensions"
    }
  ]
}

Key schema elements:

• nodes: System components with id, label, type (external, service, store, compute), and optional description
• flows: Directed connections with from/to node references, descriptive label, and data payload documentation

Rendering the Data Flow Diagram

CLI Rendering

Invoke the Node.js renderer directly for build pipelines or automation:

node archify/renderers/dataflow/render-dataflow.mjs \
     docs/gallery/sources/product-analytics.dataflow.json \
     output/product-analytics.dataflow.html

The render-dataflow.mjs script:

1. Validates the input JSON against the data flow schema
2. Computes layout positions for nodes and edge routing
3. Generates a self-contained HTML file with embedded CSS, JavaScript, and SVG

Web UI Rendering

For interactive development, open [docs/start.html](https://github.com/tt-a1i/archify/blob/main/docs/start.html) with query parameters:

start.html?type=dataflow&source=gallery

This loads the JSON IR, executes the renderer in-browser, and displays the interactive diagram. The gallery page ([docs/gallery.html](https://github.com/tt-a1i/archify/blob/main/docs/gallery.html), lines 452-453) uses this pattern for its "Create this type" links.

Interacting with Generated Diagrams

The output HTML includes a feature toolbar implemented in scripts/site-copy.mjs, lines 13-31:

• Theme toggle: Switch between light and dark modes via URL parameter ?theme=dark
• Embed mode: Clean presentation for iframe inclusion using ?embed=1
• SVG export: Extract the underlying vector graphic for external documentation

Embedding Data Flow Diagrams in Documentation

Include rendered diagrams directly in README files, wikis, or static sites:

<iframe 
  src="output/product-analytics.dataflow.html?embed=1&theme=dark"
  width="100%" 
  height="600" 
  loading="lazy"
  title="Product Analytics Data Flow Diagram">
</iframe>

For GitHub compatibility, export the SVG and reference it as a standard image:

![Product Analytics Data Flow](docs/diagrams/product-analytics.dataflow.svg)

Summary

• Install the Archify skill globally using npx skills add
• Select dataflow as the diagram type in web UI or CLI
• Input either natural language (auto-converted) or structured *.dataflow.json
• Render via render-dataflow.mjs for CLI pipelines or [start.html](https://github.com/tt-a1i/archify/blob/main/docs/start.html) for interactive use
• Reference product-analytics.dataflow.json as a complete schema example

Frequently Asked Questions

What file extension should I use for data flow JSON files?

Archify recognizes *.dataflow.json as the canonical extension for data flow intermediate representations. The renderer detects this pattern in render-dataflow.mjs to apply appropriate parsing logic.

Can I generate data flow diagrams from existing code repositories?

Yes. In the web UI, select Use a repository instead of Just describe it. Archify analyzes the repository structure to infer data movement patterns between components, then generates the JSON IR automatically.

How do I customize the visual styling of generated diagrams?

Pass theme and embed query parameters to the output HTML, or modify the CSS variables in the generated file. For permanent changes, edit the renderer source in archify/renderers/dataflow/ before building.

Are data flow diagrams purely static or interactive?

The default output is interactive: nodes support tooltips on hover, the toolbar enables theme switching, and zoom/pan controls assist navigation. Add ?embed=1 to disable chrome for static presentation contexts.

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