# Sankey Diagram Conservation and Geometry Gate Verification in Diagram-Design

> Diagram Design verifies Sankey diagrams using flow conservation and geometry gate validation for accurate data and visual integrity. Ensure your diagrams are correct.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-09

---

**Diagram-Design verifies Sankey diagrams by enforcing flow conservation (ensuring incoming values equal outgoing values) and validating geometry gates (confirming polygons are closed, non-self-intersecting, and correctly aligned) to guarantee both data accuracy and visual integrity.**

The **Diagram-Design** repository provides robust verification utilities that ensure generated diagrams meet strict visual and data-integrity standards. Sankey diagram conservation and geometry gate verification serve as critical quality gates within this toolchain, preventing misleading visualizations and malformed geometries from reaching production environments.

## Architecture of Sankey Verification

The verification system splits responsibilities across specialized modules to promote reusability and maintainability across the codebase.

### Core Verification Components

- **[`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py)**: The main entry point that parses diagram JSON, computes source-to-target flow totals, and validates SVG-like gate geometries. It raises errors when conservation rules are violated or when gate polygons fail geometric constraints.

- **[`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py)**: A shared geometry engine supplying reusable functions like `is_polygon_valid` and `gate_alignment_ok`. This module ensures a single source of truth for geometric correctness across all diagram types, including ridgeline and polar charts.

- **[`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-plugin-package.py)**: Validates that the Sankey verification script is properly bundled in the published plugin package with all dependencies declared in [`package.json`](https://github.com/cathrynlavery/diagram-design/blob/main/package.json).

- **[`commands/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/doctor.md)**: Powers the `diagram-design doctor` CLI command, which aggregates verification results including Sankey-specific flow and geometry warnings.

### The Four-Step Verification Pipeline

According to the source code in [`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py), the validation process follows this strict sequence:

1. **Input Acquisition**: The validator receives a JSON diagram description in the standard Diagram-Design format.

2. **Flow-Conservation Check**: For each node, incoming and outgoing edge values are summed. If the difference exceeds epsilon (`1e-6`), an error is recorded.

3. **Geometry Gate Check**: Using helpers from [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py), the script confirms each gate polygon has a closed path (`first_point == last_point`), contains no self-intersections, and aligns orthogonally with the node's flow direction via `gate_alignment_ok`.

4. **Reporting**: Violations print to STDOUT and trigger a non-zero exit status for CI pipeline integration.

## Why Conservation and Geometry Verification Matters

### Preventing Data Misrepresentation

Sankey diagrams visualize quantitative flows. When conservation fails—showing more outgoing than incoming value—the diagram implies energy loss or creation that never occurred. The `1e-6` epsilon tolerance in [`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py) catches floating-point drift while maintaining strict numerical accountability.

### Protecting Rendering Integrity

Malformed geometry gates—such as self-intersecting polygons or open paths—break rendering engines, producing artifacts or invisible flows. The geometry validation in [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) protects downstream processes like SVG export and Mermaid conversion by ensuring gate polygons are mathematically sound before rendering begins.

## Implementation Examples

### Manual CLI Verification

```bash

# Verify a specific Sankey diagram

diagram-design verify-sankey ./my-sankey.json

```

Successful validation exits with status 0 and prints:

```

✅ Sankey diagram passed all checks

```

Failure scenarios report specific errors:

```

❌ Flow conservation error on node “Manufacturing”: 
   incoming = 1250.0, outgoing = 1248.9 (Δ = 1.1)
❌ Geometry gate error on edge “Coal → Electricity”: 
   gate polygon is self-intersecting

```

### CI/CD Pipeline Integration

```yaml

# .github/workflows/ci.yml

jobs:
  diagram-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Diagram-Design
        run: pip install -e .
      - name: Verify Sankey diagrams
        run: |
          for file in diagrams/**/*.json; do
            diagram-design verify-sankey "$file"
          done

```

The workflow aborts on any non-zero exit, treating malformed diagrams as merge-blocking failures.

### Programmatic Python API

```python
from diagram_design.sankey import verify_sankey
import json

with open("my-sankey.json") as fp:
    diagram = json.load(fp)

issues = verify_sankey(diagram)
if issues:
    for error in issues:
        print(error)
    raise SystemExit(1)
print("All Sankey checks passed.")

```

The `verify_sankey` function returns a list of human-readable error strings, providing a thin wrapper around the CLI logic for custom automation scripts.

## Summary

- **Flow conservation** in [`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py) ensures incoming and outgoing values match within a `1e-6` epsilon, preventing misleading quantitative visualizations.
- **Geometry gate verification** validates that Sankey polygons are closed, non-self-intersecting, and properly aligned using shared utilities from [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py).
- The modular architecture separates concerns between data validation ([`verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-sankey.py)), geometric calculations ([`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py)), and packaging ([`verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-plugin-package.py)).
- Integration options include direct CLI usage, CI/CD pipelines via exit codes, and Python API imports for programmatic workflows.

## Frequently Asked Questions

### What is flow conservation in Sankey diagrams?

Flow conservation requires that the total value entering a node equals the total value leaving it. In [`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py), this calculation sums all incoming edge values and compares them against outgoing sums, raising an error if the difference exceeds the floating-point epsilon of `1e-6`.

### How does Diagram-Design detect self-intersecting gate polygons?

The [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) module implements an `is_polygon_self_intersecting` check that analyzes the gate's path data. This function verifies that the polygon's edges do not cross each other and that the path closes properly (`first_point == last_point`), which [`scripts/verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sankey.py) calls during the geometry gate verification phase.

### What exit codes does the Sankey verifier return?

The verifier exits with status 0 when all checks pass. Any flow conservation violation or geometry gate error triggers a non-zero exit status, specifically designed to fail CI/CD pipelines and prevent merges of invalid diagrams.

### Can the geometry verification utilities handle other diagram types?

Yes. The [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) module provides reusable functions like `is_polygon_valid` and `gate_alignment_ok` that support multiple diagram validators including ridgeline and polar charts. Improvements to this shared module automatically benefit all dependent diagram types.