# diagram-renderer

> Automatically renders DOT/Graphviz files to SVG and opens them in the browser.
Provides instant visual feedback during Phase 2 Discovery when architecture diagrams are generated.
Copyright (c) 2025 James J Ter Beest III. All Rights Reserved.

- Author: James Ter Beest
- Repository: turbobeest/claude-dev-pipeline
- Version: 20260108030515
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/turbobeest/claude-dev-pipeline
- Web: https://mule.run/skillshub/@@turbobeest/claude-dev-pipeline~diagram-renderer:20260108030515

---

---
skill_name: diagram-renderer
activation_code: DIAGRAM_RENDERER_V1
version: 1.0.0
phase: 2
phases_applicable: [2, 6]
category: utility
prerequisites:
  - graphviz installed (dot command)
outputs:
  - .claude/rendered-diagrams/*.svg
  - .claude/rendered-diagrams/*.png
description: |
  Automatically renders DOT/Graphviz files to SVG and opens them in the browser.
  Provides instant visual feedback during Phase 2 Discovery when architecture diagrams are generated.
  Copyright (c) 2025 James J Ter Beest III. All Rights Reserved.
---

# Diagram Auto-Renderer Skill

## Purpose

Automatically renders DOT/Graphviz files to SVG and opens them in the browser the moment they are created. Provides instant visual feedback during Phase 2 Discovery when architecture diagrams (C4 model) are generated.

## When to Use

- During Phase 2 Discovery when architecture diagrams are being created
- When generating C4 model diagrams (Context, Container, Component, Code)
- Any time a DOT/Graphviz file is written to the project
- During Phase 6 Specification when system diagrams need visualization
- User requests diagram rendering or asks to see a visual
- Example triggers:
  - Writing any `.dot` file (automatically detected)
  - "Render the architecture diagram"
  - "Show me the C4 context diagram"
  - "Visualize the data flow"

## Activation

**Automatic**: PostToolUse hook triggers when any `.dot` file is written.

No manual activation needed - diagrams render and open automatically.

## Behavior

1. **Detect DOT Write**
   - PostToolUse hook monitors Write tool operations
   - Triggers only for files ending in `.dot`

2. **Render to SVG**
   - Uses Graphviz `dot` command to render to SVG (scalable, high quality)
   - Falls back to PNG if SVG fails
   - Output saved to `.claude/rendered-diagrams/`

3. **Open in Browser**
   - Automatically opens rendered diagram in default browser
   - Cross-platform: macOS (`open`), Linux (`xdg-open`), Windows (`start`)

4. **Inject Confirmation**
   - Injects message confirming render success
   - Shows paths to source and rendered files

## Requirements

**Graphviz must be installed**:

```bash
# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt install graphviz

# Windows
choco install graphviz
```

## Files

| File | Purpose |
|------|---------|
| `hooks/diagram-auto-render.sh` | PostToolUse hook |
| `scripts/render_dot.py` | Render utility script |
| `.claude/rendered-diagrams/` | Output directory for rendered images |

## Output Location

Rendered files are saved to `.claude/rendered-diagrams/` with naming:

```
{path}_{filename}.svg
```

Example:
- Source: `docs/architecture/context.dot`
- Rendered: `.claude/rendered-diagrams/docs_architecture_context.svg`

## Manual Usage

You can also render DOT files manually:

```bash
# Render to SVG
python3 scripts/render_dot.py input.dot output.svg

# Render to PNG with high DPI
python3 scripts/render_dot.py input.dot output.png --dpi 300

# Use different layout engine
python3 scripts/render_dot.py network.dot output.svg --engine neato
```

## Layout Engines

| Engine | Use Case |
|--------|----------|
| `dot` | Hierarchical/directed graphs (default) |
| `neato` | Undirected graphs, network diagrams |
| `fdp` | Large undirected graphs |
| `sfdp` | Very large graphs (1000+ nodes) |
| `circo` | Circular layouts |
| `twopi` | Radial layouts |

## C4 Diagram Examples

### Context Diagram (Level 1)

```dot
digraph C4_Context {
    rankdir=TB;
    node [shape=box, style=filled, fontname="Arial"];

    // Actors
    user [label="User\n[Person]", shape=ellipse, fillcolor="#08427B", fontcolor=white];

    // System
    system [label="My System\n[Software System]", fillcolor="#1168BD", fontcolor=white];

    // External
    external [label="External API\n[External System]", fillcolor="#999999", fontcolor=white];

    // Relationships
    user -> system [label="Uses"];
    system -> external [label="Calls"];
}
```

### Container Diagram (Level 2)

```dot
digraph C4_Container {
    rankdir=TB;
    compound=true;
    node [shape=box, style=filled, fontname="Arial"];

    subgraph cluster_system {
        label="System Boundary";
        style=filled;
        fillcolor="#E8E8E8";

        web [label="Web App\n[Next.js]", fillcolor="#438DD5", fontcolor=white];
        api [label="API\n[Node.js]", fillcolor="#438DD5", fontcolor=white];
        db [label="Database\n[PostgreSQL]", fillcolor="#438DD5", fontcolor=white];
    }

    user [label="User", shape=ellipse, fillcolor="#08427B", fontcolor=white];

    user -> web;
    web -> api;
    api -> db;
}
```

## Hook Configuration

Already wired in `config/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "hooks/diagram-auto-render.sh"
          }
        ]
      }
    ]
  }
}
```

## Troubleshooting

### Diagram not rendering

1. Check Graphviz installed: `dot -V`
2. Check DOT syntax is valid
3. Check hook is wired in settings.json

### Diagram not opening

1. Check OS-specific browser opener is working
2. Verify file was created in `.claude/rendered-diagrams/`
3. Open manually: `open .claude/rendered-diagrams/*.svg`

### Poor quality

- Use SVG (default) for best quality
- For PNG, increase DPI: `--dpi 300`

## Related

- `dot-architect` agent - Creates DOT diagrams
- `mermaid-expert` agent - Alternative diagram format
- Phase 2 Discovery - When architecture diagrams are created