---
name: draw-diagram
description: "Generate inline SVG teaching diagrams using tools/draw-diagram.py. Use when creating architecture stacks, data flows, or hub-and-spoke diagrams for lessons. Trigger: draw diagram, generate SVG, architecture diagram, flow diagram, visual for lesson."
metadata:
  type: reference
  invocation: both
  practice: null
---

# Draw Diagram

Generate teaching diagrams as inline SVG via `tools/draw-diagram.py`. Output goes to stdout — paste directly into lesson HTML.

## Prerequisites

```bash
mise run install-deps  # installs drawsvg
```

## Commands

### Layered Stack (architecture layers, top-to-bottom)

```bash
python tools/draw-diagram.py --type stack --data '{
  "layers": [
    {"label": "AWS Glue Catalog", "color": "blue"},
    {"label": "Metadata (JSON)", "color": "amber", "subtitle": "schema + snapshots"},
    {"label": "Data Files (Parquet)", "color": "green"}
  ],
  "arrows": ["points to", "lists files"]
}'
```

### Left-to-Right Flow (pipelines, sequences)

```bash
python tools/draw-diagram.py --type flow --data '{
  "nodes": [
    {"label": "Producers", "color": "blue"},
    {"label": "Glue ETL", "color": "amber"},
    {"label": "Iceberg Table", "color": "green"},
    {"label": "Athena", "color": "blue"}
  ],
  "arrows": ["raw events", "write Parquet", "query"]
}'
```

### Hub-and-Spoke (central service + connections)

```bash
python tools/draw-diagram.py --type hub --data '{
  "center": {"label": "Glue Catalog", "color": "blue"},
  "spokes": [
    {"label": "Athena", "color": "gray"},
    {"label": "EMR Spark", "color": "gray"},
    {"label": "Redshift", "color": "gray"},
    {"label": "Glue ETL", "color": "gray"}
  ]
}'
```

### Graph (fan-out/fan-in, groups, auto-layout)

The most flexible type. Nodes are named by ID, edges can connect one-to-many or many-to-one. Layout is computed automatically via topological ranking.

```bash
python tools/draw-diagram.py --type graph --data '{
  "direction": "LR",
  "nodes": [
    {"id": "lb", "label": "Load Balancer", "preset": "infrastructure"},
    {"id": "w1", "label": "Worker 1", "preset": "concept"},
    {"id": "w2", "label": "Worker 2", "preset": "concept"},
    {"id": "db", "label": "Database", "preset": "example"}
  ],
  "edges": [
    {"from": "lb", "to": ["w1", "w2"], "label": "distribute"},
    {"from": ["w1", "w2"], "to": "db", "label": "write"}
  ],
  "groups": [
    {"label": "Compute", "nodes": ["w1", "w2"]}
  ]
}'
```

**Features:**
- `"from"` and `"to"` accept single ID or array (fan-out/fan-in)
- `"groups"` draw a dashed background rectangle around named nodes
- `"direction"`: `"LR"` (left-to-right) or `"TB"` (top-to-bottom)
- Auto-ranks nodes by dependency depth (sources left/top, sinks right/bottom)

## Color Vocabulary & Presets

Colors can be specified by name or preset. Presets map teaching intent to color:

| Preset | Color | Use for |
|--------|-------|---------|
| `concept` | blue | The thing being taught, primary components |
| `example` | green | Concrete instances, outputs, results |
| `process` | amber | Processing, transformation, operational steps |
| `anti-pattern` | red | Problems, errors, what not to do |
| `infrastructure` | gray | Supporting services, neutral context |

Use `"preset": "concept"` or `"color": "blue"` — both work.

## Output

Prints SVG XML to stdout. Embed in lessons:

```html
<p>The Iceberg metadata tree has three layers:</p>
<!-- paste SVG output here -->
```

Always add a one-line verbal summary above the diagram (dual coding principle).

## When to use this vs raw SVG vs D2

| Situation | Use |
|-----------|-----|
| Standard teaching diagram (stack/flow/hub) | `draw-diagram.py` |
| Custom layout or annotated component | Raw inline SVG from `assets/svg-patterns.md` |
| Complex auto-layout (sequence, state machine) | D2 (`d2 input.d2 output.svg`) |

## Limitations

- No auto-layout — positions are grid-based (good enough for 3-7 elements)
- No interactive elements (use progressive-reveal.js `data-step` attrs for that)
- Hub diagram with >6 spokes gets crowded — split into multiple diagrams