# How to Configure Archify Data‑Flow Diagrams for Product Analytics: A Complete Guide
> Learn to configure Archify dataflow diagrams for product analytics using a typed JSON file. Generate interactive HTML visualizations with the Archify CLI. Get the complete guide.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-03
---
**Archify dataflow diagrams for product analytics are configured through a typed JSON file that defines pipeline stages, service nodes, directed data flows, and explanatory cards, which you then render using the Archify CLI to generate interactive HTML visualizations.**
To visualize your product analytics architecture in tt-a1i/archify, you create a schema-compliant JSON configuration that maps data sources, consent gates, warehouses, and consumption endpoints. When you configure archify dataflow diagrams for product analytics, you edit a single declarative file that the CLI transforms into production-ready documentation, complete with animated edges and privacy-boundary annotations.
## Understanding the Core Configuration Structure
Every dataflow diagram in Archify follows a strict JSON schema with seven primary sections. In [`archify/examples/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/product-analytics.dataflow.json), the root object contains `schema_version`, `diagram_type`, `meta`, `stages`, `nodes`, `flows`, and `cards`.
**Schema version and diagram type** establish compatibility. You must set `schema_version` to `1` and `diagram_type` to `"dataflow"` to access the current feature set.
**Metadata controls** reside in the `meta` object, defining human-readable titles, output file paths, canvas dimensions via `viewBox`, and animation presets such as `"trace"` or `"none"`.
**Stages** define the logical columns that group your architecture horizontally—typically representing phases like Sources, Ingest, Process, Store, and Consume.
**Nodes** represent individual components—databases, microservices, security gates, or front-end applications—each positioned within a specific stage and row.
**Flows** create the directed edges between nodes, supporting custom routing through bend points, classification labels, and styling variants for security or emphasis.
**Cards** provide side-panel narrative context, grouping related facts into color-coded explanations that appear alongside the rendered diagram.
## Step‑by‑Step Configuration Guide
### Adjust Metadata and Output Settings
Start by customizing the `meta` object to reflect your environment. Change the `title` and `subtitle` to describe your specific product analytics stack, and set the `output` path to control where the generated HTML file lands.
```json
"meta": {
"title": "SaaS Product Analytics Pipeline",
"subtitle": "Event collection → Consent gate → Warehouse → Dashboards",
"output": "examples/my-analytics.html",
"viewBox": [1080, 760],
"animation": "trace",
"quality_profile": "showcase"
}
```
The `viewBox` array defines your canvas width and height in pixels—expand these values if you add many nodes to prevent overlap. The `quality_profile` field accepts values like `"showcase"` or `"draft"` to control rendering fidelity.
### Define Your Pipeline Stages
Stages create the horizontal columns that organize your architecture. Each stage is an object with a `label` property, arranged in the order that data flows through your system.
```json
"stages": [
{ "label": "Sources" },
{ "label": "Ingest" },
{ "label": "Process" },
{ "label": "Store" },
{ "label": "Consume" }
]
```
To insert a custom stage—such as an **Enrichment** layer between Process and Store—simply add the object at the appropriate index in the array. Stages are zero-indexed, so position 0 appears as the leftmost column.
### Add Nodes for Each Component
Nodes represent the concrete services and storage systems in your pipeline. Each node requires a unique `id`, a `type` (such as `"frontend"`, `"database"`, or `"security"`), display labels, and positional coordinates via `stage` and `row` indices.
```json
{
"id": "realtime-dash",
"type": "backend",
"label": "Realtime Dashboard",
"sublabel": "Live metrics view",
"stage": 4,
"row": 3,
"tag": "live"
}
```
The `stage` property maps to the index of your stages array, while `row` controls vertical positioning within that column. Use the `tag` field to add contextual badges that appear on the node shape.
### Map Data Flows Between Nodes
Flows define directed edges using `from` and `to` properties that reference node IDs. You can customize the visual routing using `fromSide` and `toSide` (e.g., `"left"`, `"right"`, `"top"`, `"bottom"`), and create polyline bends with the `via` array of coordinate pairs.
```json
{
"id": "warehouse-to-realtime",
"from": "warehouse",
"to": "realtime-dash",
"label": "materialized view",
"classification": "read‑only",
"variant": "default",
"fromSide": "right",
"toSide": "left",
"via": [[880, 385], [880, 460]],
"labelAt": [860, 420]
}
```
The `via` array accepts multiple `[x, y]` coordinates to route lines around obstacles, while `labelAt` positions the flow label at a specific canvas coordinate. Use `variant` values like `"emphasis"` or `"security"` to apply semantic color coding that highlights PII boundaries or critical paths.
### Create Explanatory Cards
Cards appear in side panels to explain higher-level concepts like privacy guards or data retention policies. Each card contains a `dot` color, a `title`, and an `items` array of bullet strings.
```json
{
"dot": "purple",
"title": "Privacy Guard",
"items": [
"All PII passes through the Consent Gate before storage.",
"Encrypted vault isolates raw identifiers from analytics queries."
]
}
```
Place cards in the `cards` array to provide narrative context that complements the visual diagram, making your documentation accessible to non-technical stakeholders.
## Complete Configuration Example
Below is a minimal, working JSON file that you can save as [`my-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/my-analytics.dataflow.json) and customize for your own pipeline. It includes essential metadata, five standard stages, six nodes representing a typical analytics stack, connecting flows, and one explanatory card.
```json
{
"schema_version": 1,
"diagram_type": "dataflow",
"meta": {
"title": "My SaaS Product Analytics",
"subtitle": "Event → Consent → Warehouse → Dashboard",
"output": "examples/my-analytics.html",
"viewBox": [1080, 760],
"animation": "trace",
"quality_profile": "showcase"
},
"stages": [
{ "label": "Sources" },
{ "label": "Ingest" },
{ "label": "Process" },
{ "label": "Store" },
{ "label": "Consume" }
],
"nodes": [
{ "id": "web", "type": "frontend", "label": "Web App", "sublabel": "SDK", "stage": 0, "row": 0, "tag": "events" },
{ "id": "edge", "type": "cloud", "label": "Edge API", "sublabel": "collector", "stage": 1, "row": 1, "tag": "TLS" },
{ "id": "consent", "type": "security", "label": "Consent Gate", "stage": 2, "row": 0, "tag": "PII guard" },
{ "id": "warehouse", "type": "database", "label": "Warehouse", "stage": 3, "row": 2, "tag": "curated" },
{ "id": "dashboard", "type": "backend", "label": "Dashboard", "stage": 4, "row": 1, "tag": "SQL" },
{ "id": "realtime", "type": "backend", "label": "Realtime Dashboard", "stage": 4, "row": 3, "tag": "live" }
],
"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-warehouse", "from": "consent", "to": "warehouse", "label": "sanitized events", "variant": "emphasis", "fromSide": "right", "toSide": "left" },
{ "id": "warehouse-dashboard", "from": "warehouse", "to": "dashboard", "label": "SQL query", "variant": "default", "fromSide": "right", "toSide": "left" },
{ "id": "warehouse-realtime", "from": "warehouse", "to": "realtime", "label": "materialized view", "variant": "default", "fromSide": "right", "toSide": "left" }
],
"cards": [
{
"dot": "emerald",
"title": "Primary Data Path",
"items": [
"Events travel from sources → ingest → process → store → consume.",
"The hot path stays clear even with secondary flows."
]
}
]
}
```
## Generate the Diagram
Once your JSON configuration is complete, use the Archify CLI to render the interactive HTML file. Run the following command from your repository root, replacing the input path with your actual filename:
```bash
node archify/bin/archify.mjs deliver dataflow archify/examples/my-analytics.dataflow.json ./my-analytics.html --quality showcase --open
```
The `deliver` command accepts the diagram type (`dataflow`), your JSON file path, the output HTML path, and optional flags for quality and auto-opening the result in your default browser.
## Summary
- **Archify dataflow diagrams** are configured via a single JSON file using schema version 1 and type `"dataflow"`.
- **Structure your pipeline** using the `stages` array to create logical columns, then place **nodes** within specific stage and row indices to represent services and databases.
- **Connect components** with **flows** that support custom routing via the `via` property and semantic styling through the `variant` field.
- **Add context** using **cards** to explain privacy boundaries, data classifications, or architectural decisions.
- **Render** your configuration using the CLI command `node archify/bin/archify.mjs deliver dataflow .json