# UV Diagram Policy — MANDATORY

**Version:** 1.0  
**Date:** 2026-04-23  
**Status:** ABSOLUTE — ZERO TOLERANCE  
**Applies to:** All UV documentation, all agent-generated documents

---

## THE RULE

**ONLY ONE DIAGRAM FORMAT IS PERMITTED: WORMWOOD_APP INTERACTIVE CANVAS**

All other "diagram" formats are **FORBIDDEN**.

---

## APPROVED DIAGRAM FORMAT

### WORMWOOD_APP Interactive Canvas

**Location:** `c:\repos\UV\wormwood-engine\docs\WORMWOOD_APP.html`

**Technology:**
- Interactive HTML canvas with JavaScript
- SVG-rendered flexible connectors (curved paths, not ASCII)
- Draggable nodes with real mouse interaction
- `nexus-core.js` + `demo-edge-creation.js` rendering engine
- CSS from `css/nexus-canvas.css`

**Characteristics:**
- Nodes are visual boxes you can click and drag
- Connectors are SVG `<path>` elements with curves/beziers
- Fully interactive — users can edit the graph
- Real-time execution visualization
- Multi-layer support (Data Flow → Classes → Properties → Rules)

**When to use:**
- Pipeline architecture diagrams
- Data flow visualizations
- Node sequence specifications
- ANY diagram showing connected components

**How to create:**
- Open `WORMWOOD_APP.html` in browser
- Use Palette to add nodes
- Drag nodes to canvas
- Click source node, then target node to create connector
- Export/save pipeline YAML

---

## FORBIDDEN "DIAGRAM" FORMATS

### ❌ FORBIDDEN: ASCII Arrow Pseudo-Diagrams

**Examples of VIOLATIONS (all FORBIDDEN):**

```html
<!-- VIOLATION 1: Flex layout with text arrows -->
<div class="nxd-flow">
  <div class="nxd-node">Source</div>
  <div class="nxd-arrow">→</div>
  <div class="nxd-node">Transform</div>
  <div class="nxd-arrow">→</div>
  <div class="nxd-node">Sink</div>
</div>
```

**Why forbidden:** This is NOT a diagram. It is styled text in a flex container pretending to be a diagram. The "arrows" are Unicode characters, not vector graphics. No interactivity, no flexible connectors, not maintainable.

```html
<!-- VIOLATION 2: CSS-styled boxes with pseudo-connectors -->
<div class="pipeline-diagram">
  <div class="node">Azure SQL</div>
  <div class="connector"></div>
  <div class="node">Nexus</div>
</div>
```

**Why forbidden:** CSS borders/backgrounds do not create diagrams. This is layout abuse.

```markdown
<!-- VIOLATION 3: Markdown ASCII art -->
[Source] --> [Transform] --> [Sink]

   ┌─────────┐
   │  Node   │
   └────┬────┘
        │
        ▼
   ┌─────────┐
   │  Node   │
   └─────────┘
```

**Why forbidden:** ASCII art is not a diagram. Non-scalable, non-editable, breaks with fonts.

---

## WHAT TO USE INSTEAD OF "DIAGRAMS"

When you CANNOT use WORMWOOD_APP interactive canvas (e.g., in static concept documents), use:

### ✅ APPROVED: Tables

**Good for:** Component relationships, data models, node sequences

```html
<table>
  <thead>
    <tr><th>Stage</th><th>Component</th><th>Function</th></tr>
  </thead>
  <tbody>
    <tr><td>1</td><td>SourceIngest</td><td>Query Azure SQL</td></tr>
    <tr><td>2</td><td>AiTransform</td><td>Classify document</td></tr>
    <tr><td>3</td><td>GraphBuild</td><td>Write to deltaPrism</td></tr>
  </tbody>
</table>
```

### ✅ APPROVED: Ordered/Unordered Lists

**Good for:** Pipeline steps, data flow descriptions

```markdown
**Pipeline Flow:**

1. **SourceIngest** — Query Azure SQL for attachments
2. **AiTransform (Classify)** — Determine document type
3. **AiTransform (Extract)** — Extract structured fields
4. **GraphBuild** — Encrypt and write to deltaPrism
5. **CacheRefresh** — Validate graph stats
6. **Egress** — Mark source rows as processed
```

### ✅ APPROVED: Prose Description

**Good for:** Complex relationships that don't fit tables

```
The pipeline consists of seven stages. First, SourceIngest queries Azure SQL
for all attachments with TextExtractionStatus='done'. These flow to AiTransform
(Classify) which determines the document type. Documents classified as 'unknown'
are logged and skipped. Valid documents flow to AiTransform (Extract) which
extracts structured fields per class schema...
```

### ✅ APPROVED: Hierarchical Structure (nested divs with indentation)

**Good for:** Tree structures, nested relationships

```html
<div style="line-height:2;">
  <div style="padding-left:0;">Level 1: Data Flow</div>
  <div style="padding-left:40px;">Level 2: Classes (Contract, Brief, Deliverable)</div>
  <div style="padding-left:80px;">Level 3: Properties (client_name, budget, tech_stack)</div>
  <div style="padding-left:120px;">Level 4: Relations (ContractParty, BriefSource)</div>
</div>
```

---

## ENFORCEMENT

### For Agents

Before creating ANY diagram in documentation:

1. **Check:** Is this an WORMWOOD_APP interactive canvas? 
   - YES → Proceed
   - NO → STOP

2. **If not WORMWOOD_APP:**
   - Convert to table, list, or prose description
   - NEVER use ASCII arrows, flex layouts, or CSS-styled "connectors"

### For Document Review

All documents containing `.nxd-flow`, `.nxd-arrow`, or ASCII arrow characters (`→`, `←`, `↔`, `⇒`, `⟶`) are **REJECTED** unless they are part of WORMWOOD_APP canvas code.

### Penalty for Violation

- Document marked UNAPPROVED
- Author must rewrite with approved formats
- Document violation logged in KNOWN_ISSUES.md

---

## RATIONALE

**Why this policy exists:**

1. **WORMWOOD_APP is the product** — Our diagrams should showcase our own technology, not fake it with CSS
2. **Maintainability** — ASCII "diagrams" become unmaintainable as complexity grows
3. **Consistency** — One diagram format across all UV documentation
4. **Interactivity** — Real diagrams are editable, exportable, executable
5. **Professional quality** — SVG connectors >> Unicode arrows

**If you can't use WORMWOOD_APP, don't pretend you have a diagram. Use tables/lists instead.**

---

## EXAMPLES FROM REAL VIOLATIONS

### BEFORE (FORBIDDEN):

```html
<div class="nxd-wrap">
<div class="nxd-section-label">End-to-End Architecture</div>
<div class="nxd-flow">
<div class="nxd-node"><div class="nxd-node-label">Z1.4 Azure SQL</div></div>
<div class="nxd-arrow">→</div>
<div class="nxd-node trigger"><div class="nxd-node-label">Nexus UC4</div></div>
<div class="nxd-arrow">→</div>
<div class="nxd-node ai"><div class="nxd-node-label">Wormwood</div></div>
</div>
</div>
```

**Problem:** Text arrows, flex layout, zero interactivity, breaks with screen readers.

### AFTER (APPROVED):

```html
<h3>End-to-End Architecture</h3>
<table>
  <thead>
    <tr><th>Stage</th><th>Component</th><th>Role</th></tr>
  </thead>
  <tbody>
    <tr><td>1</td><td>Z1.4 Azure SQL</td><td>Source data (61,000 attachments)</td></tr>
    <tr><td>2</td><td>Nexus UC4</td><td>Pipeline orchestration</td></tr>
    <tr><td>3</td><td>Wormwood</td><td>AI classification + extraction</td></tr>
    <tr><td>4</td><td>deltaPrism</td><td>Graph storage</td></tr>
    <tr><td>5</td><td>Relica</td><td>Read-only serving layer</td></tr>
    <tr><td>6</td><td>ARC / Apps</td><td>Consumer applications</td></tr>
  </tbody>
</table>
```

**Result:** Clear, accessible, maintainable, professional.

---

## SUMMARY

### DO
- Use WORMWOOD_APP interactive canvas for all pipeline/architecture diagrams
- Use tables for component relationships
- Use lists for sequential steps
- Use prose for complex descriptions

### DON'T
- Use ASCII arrows (`→`, `←`, etc.) in "diagrams"
- Use flex layouts to fake visual connectors
- Use CSS borders/backgrounds as "diagram elements"
- Call it a "diagram" if it's not interactive SVG

---

**Questions? See WORMWOOD_APP.html for the reference implementation.**