How Archify's Data Flow Diagram Handles PII Boundaries and Sensitivity Zones

Archify uses declarative classification labels and security flags to visually segregate PII zones and mark governed data hand-offs in JSON-defined data flow diagrams.

Archify is an open-source architecture visualization tool that enables teams to map complex data pipelines while enforcing privacy compliance. Its data flow diagram renderer explicitly models where personally identifiable information (PII) enters, transforms, and exits the system. By embedding sensitivity metadata directly into the diagram schema, archify's data flow diagram creates transparent PII boundaries that align technical implementation with data governance policies.

Declarative Privacy Controls in the Schema

The privacy model is defined in archify/schemas/workflow.schema.json and enforced by the renderer at build time. Two complementary attributes govern how sensitivity is surfaced visually.

The Classification Field

The classification property is a free-form string assigned to any node—whether source, processor, or storage—that describes the data sensitivity level passing through it. Common values include PII touch, approved only, and non-PII.

When archify/renderers/dataflow/render-dataflow.mjs processes the diagram, it maps these classifications to predefined visual styles. Nodes marked PII touch render in distinct colors with optional "PII" badges, creating immediate visual boundaries around sensitive data zones.

The Security Flag

The security boolean (or enum) attribute applies to both nodes and edges, indicating whether the data flow requires encryption, consent checks, or other policy controls. In the rendered output, security-flagged edges display lock-icon overlays and dashed line styles, signaling regulated hand-off points between zones.

Visualizing Sensitivity Zones

Sensitivity zones emerge as contiguous groups of nodes sharing identical classification values. The renderer applies color-coding to these zones, enabling architects to verify three critical compliance patterns:

• PII Isolation: Sensitive zones remain visually separated from non-PII infrastructure
• Policy Enforcement: Security-flagged edges appear at exact hand-off points, such as before data lakes or third-party services
• Downstream Awareness: Consumer systems inherit visual indicators of upstream sensitivity levels

This approach keeps privacy modeling language-agnostic and declarative, allowing the same JSON definition to power documentation, compliance audits, and interactive UI visualizations.

Code Examples

Example 1: Simple pipeline with PII source

{
  "nodes": [
    {
      "id": "clickstream",
      "label": "Clickstream Events",
      "type": "source",
      "classification": "PII touch"
    },
    {
      "id": "cleanser",
      "label": "PII Scrubber",
      "type": "processor",
      "classification": "PII touch"
    },
    {
      "id": "warehouse",
      "label": "Analytics Warehouse",
      "type": "storage",
      "classification": "non-PII"
    }
  ],
  "edges": [
    { "from": "clickstream", "to": "cleanser", "security": true },
    { "from": "cleanser", "to": "warehouse", "security": false }
  ]
}

In this diagram, the clickstream and cleanser nodes appear in the PII color zone, while the edge between them displays a lock icon due to security: true. The final edge to the warehouse appears as a standard connection, indicating sanitized data.

Example 2: Multiple sensitivity zones

{
  "nodes": [
    { "id": "auth", "label": "Auth Service", "classification": "PII touch" },
    { "id": "profile", "label": "User Profiles", "classification": "PII touch" },
    { "id": "billing", "label": "Billing DB", "classification": "approved only" },
    { "id": "analytics", "label": "Analytics DB", "classification": "non-PII" }
  ],
  "edges": [
    { "from": "auth", "to": "profile", "security": true },
    { "from": "profile", "to": "billing", "security": true },
    { "from": "billing", "to": "analytics", "security": false }
  ]
}

The renderer produces a red PII zone for the auth and profile nodes, an orange zone for the billing database, and a green non-PII zone for analytics. Both security-flagged edges render with lock icons, highlighting governance checkpoints.

Key Implementation Files

Understanding the complete PII handling system requires examining these specific source files:

• archify/schemas/workflow.schema.json: Defines the canonical schema for classification and security properties on nodes and edges.
• archify/renderers/dataflow/render-dataflow.mjs: The JavaScript implementation that parses JSON definitions, applies classification-based styling rules, and generates the final diagram output.
• archify/renderers/dataflow/README.md: Documents the specific styling conventions and mapping logic between classification values and visual attributes.
• archify/SKILL.md: Provides authoring guidelines for specifying sensitivity levels and emphasizes best practices for privacy-aware diagram construction.

Summary

• Archify's data flow diagram uses the classification field to tag nodes with sensitivity levels like PII touch or non-PII, creating distinct color-coded zones.
• The security flag marks edges and nodes requiring special governance, rendering lock icons and dashed lines to indicate regulated data flows.
• These mechanisms are defined in workflow.schema.json and processed by render-dataflow.mjs to generate compliance-ready visualizations.
• Sensitivity zones enable teams to verify PII isolation, policy enforcement points, and downstream data awareness directly in the architecture diagrams.

Frequently Asked Questions

How do I mark a data source as containing PII in Archify?

Add the classification property with the value PII touch to the node definition in your JSON workflow file. When rendered by render-dataflow.mjs, the node will appear in the PII color zone with an appropriate badge.

Can I customize the colors used for different sensitivity classifications?

Yes. The styling rules are configurable in the data flow renderer configuration. While archify/schemas/workflow.schema.json defines the structure, the specific color mappings and badge styles are managed through the renderer's style rules documented in archify/renderers/dataflow/README.md.

What is the difference between classification and security in Archify's schema?

The classification field describes the data sensitivity level (e.g., PII, confidential, public) and primarily affects node coloring and zone grouping. The security flag indicates whether technical controls like encryption or access restrictions apply, affecting edge styling with lock icons and dashed lines.

Does Archify validate that PII zones do not leak into non-PII zones automatically?

No, the renderer visualizes the boundaries but does not perform static analysis on data flows. Architects must manually verify that edges between zones have appropriate security flags and that transformations properly sanitize data before it enters non-PII classified nodes.

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