How to Create Dataflow Diagrams with PII Boundaries Using Archify

Archify renders data‑flow diagrams from a JSON‑IR representation and highlights Personally Identifiable Information (PII) boundaries when nodes declare "type": "security" and flows declare "variant": "security".

The tt-a1i/archify repository provides a declarative toolset for visualizing system architectures through code. When you create dataflow diagrams with PII boundaries using Archify, you annotate specific components in the JSON‑IR (intermediate representation) to generate visually distinct privacy boundaries in the final SVG output.

Understanding the JSON‑IR Structure for PII Boundaries

Archify’s data‑flow schema, defined in archify/schemas/dataflow.schema.json, supports explicit security markings. These annotations trigger the renderer to apply special styling that distinguishes privacy‑critical segments from standard data flows.

Security Nodes with type: "security"

Nodes that handle sensitive data—such as Consent Gates or Identity Vaults—must declare "type": "security" in their definition. This property instructs the renderer to apply a special icon or color coding, making the component instantly recognizable as a PII guard.

Security Flows with variant: "security"

Edges that transport personally identifiable information require the "variant": "security" property. According to the benchmark transcripts in benchmarks/ordinary-model-floor/results/2026-07-26-pi-three-models.json, these flows render as dashed‑rose lines that visually demarcate the privacy perimeter.

Step‑by‑Step Guide to Modeling PII Boundaries

Follow this workflow to mark PII boundaries in your architecture diagrams:

1. Copy a template from archify/examples/product-analytics.dataflow.json to establish the base structure.

2. Identify PII‑touching components such as Consent Gates, Identity Vaults, or Quarantine systems within your architecture.

3. Mark security nodes by adding "type": "security" to the relevant node objects in the JSON.

4. Annotate PII flows by setting "variant": "security" on any edge that crosses a privacy boundary.

5. Add explanatory cards (optional) to provide context about the privacy boundary; these appear as call‑out panels in the rendered output.

6. Render the diagram using the CLI provided by archify/package.json.

Annotating Nodes and Edges in Practice

The following excerpt from a dataflow definition demonstrates the correct syntax for PII boundaries. The Consent Gate and Identity Vault are flagged as security nodes, while the connecting edges use the security variant to indicate PII transmission:

{
  "diagram_type": "dataflow",
  "nodes": [
    { "id": "web-app", "label": "Web App" },
    { "id": "edge-api", "label": "Edge API" },
    { "id": "consent-gate", "label": "Consent Gate", "type": "security" },
    { "id": "pii-vault", "label": "Identity Vault", "type": "security" },
    { "id": "warehouse", "label": "Data Warehouse" }
  ],
  "flows": [
    { "source": "web-app", "target": "edge-api", "variant": "emphasis" },
    { "source": "edge-api", "target": "consent-gate", "variant": "security" },
    { "source": "consent-gate", "target": "pii-vault", "variant": "security" },
    { "source": "pii-vault", "target": "warehouse", "variant": "emphasis" }
  ]
}

In this configuration, the renderer automatically draws distinct boundaries around the PII‑protected segment, making the privacy architecture obvious to reviewers and auditors.

Rendering the Diagram

Execute the rendering command through the CLI defined in archify/package.json. The tool processes the JSON‑IR and applies the security styling automatically:

npx archify render dataflow --input product-analytics.dataflow.json --output diagram.svg

The resulting SVG highlights the PII boundaries with the dashed‑rose styling and security node icons, providing immediate visual feedback on data privacy controls.

Summary

• Archify uses JSON‑IR to define dataflow diagrams, with the schema located at archify/schemas/dataflow.schema.json.
• PII nodes require "type": "security" to render as privacy guards.
• PII flows require "variant": "security" to display as dashed‑rose boundary lines.
• Reference implementations exist in archify/examples/product-analytics.dataflow.json and archify/examples/event-stream.dataflow.json.
• Rendering occurs via npx archify render dataflow as specified in archify/package.json.

Frequently Asked Questions

What file format does Archify use to define dataflow diagrams?

Archify utilizes a JSON‑IR (intermediate representation) format. The structure is validated against archify/schemas/dataflow.schema.json, which defines valid fields for nodes, flows, and security variants.

How does Archify visually distinguish PII boundaries in the output?

When the renderer encounters "type": "security" on nodes or "variant": "security" on flows, it applies distinct visual styles. Security nodes receive special icons or color coding, while security flows render as dashed‑rose lines or highlighted boxes that clearly demarcate the privacy perimeter.

Can I use existing templates to model PII boundaries?

Yes. The repository includes archify/examples/product-analytics.dataflow.json, which demonstrates a full‑featured dataflow with PII boundaries. You can copy this template and modify the node IDs and labels to match your specific architecture while preserving the security annotations.

Where is the CLI command defined for rendering diagrams?

The CLI entry point is configured in archify/package.json. The command npx archify render dataflow accepts an input JSON file and outputs an SVG diagram with all security styling applied automatically.

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