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

> Learn how Archify visualizes PII boundaries and sensitivity zones in data flow diagrams using declarative labels and security flags for governed data hand-offs. Explore secure data management.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-07-14

---

**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`](https://github.com/tt-a1i/archify/blob/main/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*

```json
{
  "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*

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/README.md)**: Documents the specific styling conventions and mapping logic between classification values and visual attributes.
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.