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

> Learn to create data flow diagrams with Archify. Convert descriptions to interactive diagrams easily using the Archify dataflow renderer.

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

---

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

```bash
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)](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/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`](https://github.com/tt-a1i/archify/blob/main/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/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)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json):

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

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

```

The [`render-dataflow.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/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)](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)](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`](https://github.com/tt-a1i/archify/blob/main/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:

```html
<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:

```markdown
![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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/render-dataflow.mjs) for CLI pipelines or [[`start.html`](https://github.com/tt-a1i/archify/blob/main/start.html)](https://github.com/tt-a1i/archify/blob/main/docs/start.html) for interactive use
- **Reference** [product-analytics.dataflow.json](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/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/`](https://github.com/tt-a1i/archify/tree/main/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.