How to Configure Archify Data‑Flow Diagrams for Product Analytics: A Complete Guide

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

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

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

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

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

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

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

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 <input>.json <output>.html.

Frequently Asked Questions

What file format does Archify use for dataflow diagrams?

Archify uses a typed JSON format with a specific schema. Your configuration file must declare "schema_version": 1 and "diagram_type": "dataflow" at the root level, then define meta, stages, nodes, flows, and optional cards arrays. The complete schema reference is documented in archify/schemas/README.md within the repository.

How do I add a new stage between existing columns in my diagram?

Insert a new stage object with a label property at the appropriate index in the stages array. Since stages are zero-indexed, adding an object at index 2 places it between existing stages at indices 1 and 2 (which then becomes index 3). Update the stage property on any affected nodes to reflect the new indices.

Can I customize the appearance of data flow lines between nodes?

Yes. Use the variant property on flow objects to apply semantic colors like "emphasis" or "security". Control physical routing with the via array, which accepts coordinate pairs [x, y] to create polyline bends. You can also set fromSide and toSide to specify which edge of a node shape the line connects to.

Where can I find the complete schema documentation for Archify?

The official schema documentation resides in archify/schemas/README.md in the tt-a1i/archify repository. For runtime integration details and CLI usage patterns, reference archify/SKILL.md. The archify/examples/product-analytics.dataflow.json file serves as a complete, production-ready reference implementation demonstrating all configuration options.

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