Apex Python Diagrams

---
name: apex-python-diagrams
user-invocable: true
disable-model-invocation: false
argument-hint: "diagram or chart type, project and output path"
description: "**UTILITY SKILL** — Python diagram generation for Azure architectures, WAF/cost/compliance charts, ERDs, swimlanes, timelines, and wireframes. WHEN: 'architecture diagram', 'WAF bar chart', 'cost chart', 'ERD', 'swimlane', 'timeline', 'wireframe'. DO NOT USE FOR: inline Mermaid diagrams (apex-mermaid)."
compatibility: Works with VS Code Copilot, Claude Code, and any tool capable of running Python scripts.
license: MIT
metadata:
  author: apex
  version: "1.0"
---

# Python Diagrams & Charts

Skill for generating diagrams and charts using Python libraries: `matplotlib`
for WAF/cost/compliance visualizations, `diagrams` for architecture diagrams,
and `graphviz` for ERDs, swimlanes, timelines, and wireframes.

## Prerequisites

```bash
pip install diagrams matplotlib pillow && apt-get install -y graphviz
```

## Routing Guide

Workflow charts and library-rendered diagrams emit **both PNG and SVG** siblings via the shared
[`scripts/diagram_io.py`](scripts/diagram_io.py) helper — PNG for raster
preview, SVG for scalable / accessible / diff-friendly review. Standalone SVG
wireframes are the exception below; they do not use this helper.

| Diagram type                        | Library    | Output                |
| ----------------------------------- | ---------- | --------------------- |
| WAF bar charts                      | matplotlib | `.py` + `.png` + `.svg` |
| Cost donut / projection charts      | matplotlib | `.py` + `.png` + `.svg` |
| Compliance gap charts               | matplotlib | `.py` + `.png` + `.svg` |
| Architecture diagrams               | diagrams   | `.py` + `.png` + `.svg` |
| Swimlane / business process         | graphviz   | `.py` + `.png` + `.svg` |
| Entity-relationship diagrams        | graphviz   | `.py` + `.png` + `.svg` |
| Timeline / Gantt charts             | matplotlib | `.py` + `.png` + `.svg` |
| UI wireframes                       | SVG / graphviz | `.py` + `.svg`; PNG optional for SVG generator |

## Required Outputs (Workflow Integration)

| Step | Python chart files                                                                  |
| ---- | ----------------------------------------------------------------------------------- |
| 2    | `02-waf-scores.py/.png/.svg`                                                        |
| 3    | `03-des-cost-distribution.py/.png/.svg`, `03-des-cost-projection.py/.png/.svg`      |
| 4    | `04-dependency-diagram.py/.png/.svg`, `04-runtime-diagram.py/.png/.svg`             |
| 7    | `07-ab-cost-*.py/.png/.svg`, `07-ab-compliance-gaps.py/.png/.svg`                   |

Suffix rules: `-des` for design (Step 3), `-ab` for as-built (Step 7).

## Execution & Output Standards

Save `.py` source in `agent-output/{project}/`, then run with `python3` to
produce the `.png` + `.svg` sibling pair. Library-backed generators must import the
shared helpers from [`scripts/diagram_io.py`](scripts/diagram_io.py)
(`save_figure`, `diagram_kwargs`, `render_graphviz`) — never call
`plt.savefig`, `Diagram(outformat=...)`, or `dot.render()` directly.

For the `diagrams` library, call `embed_svg_images(Path(filename).with_suffix(".svg"))` after the
`with Diagram(...)` block exits, importing it from the same helper. Graphviz otherwise emits absolute
icon paths into the Python installation, which disappear in browser/editor previews or on another machine.
`render_graphviz` embeds icons automatically. Missing or unsupported icon files fail finalization;
do not claim completion from non-empty files alone. Inspect both the PNG and the standalone SVG, verify
every SVG image uses a `data:image/` URI, and confirm icons render without access to local package paths.
For explicit PNG-only standalone callers, skip SVG finalization; required workflow siblings remain mandatory.

The standalone `create_wireframe_svg(title, filename, layout)` writes SVG
and, when CairoSVG is installed, a PNG sibling. It returns the PNG path
after conversion or the SVG path when CairoSVG is unavailable; conversion
errors propagate. Inspect the returned path. Missing PNG does not satisfy
a workflow or caller that requires PNG: report the missing converter instead
of claiming completion. Existing helper `formats=` overrides remain available
for standalone callers; do not use them to omit required workflow siblings.

For the full conventions — design tokens (Azure blue, WAF pillar colours,
DPI 150), `graph_attr` / `node_attr` / `cluster_style` settings,
`labelloc='t'`, Arial Bold fonts, CIDR labels — read
[`references/python-charts.md`](references/python-charts.md).

For ready-to-use architecture diagram patterns (3-tier web app, hub-spoke, etc.)
including the canonical `with Diagram(... show=False, direction="TB") as d:`
template, read [`references/common-patterns.md`](references/common-patterns.md).

## Rules

**DO:** For library-backed diagrams, import `save_figure` / `diagram_kwargs` / `render_graphviz` from
[`scripts/diagram_io.py`](scripts/diagram_io.py) so every chart emits both
`.png` and `.svg` siblings · Set `show=False` · Use `direction="TB"` ·
Group in `Cluster` blocks · Set explicit `filename` · Use DPI ≥150 ·
Apply design tokens consistently · Generate WAF scores PNG+SVG when WAF
scores are assigned.

**DON'T:** Call `plt.savefig(...)`, `Diagram(..., outformat=...)`, or
`dot.render(...)` directly — always go through `diagram_io` · Use Mermaid
for charts (use matplotlib) · Let `show=True` open a viewer · Omit `filename`
(produces non-deterministic output names) · Use grouped
list-to-list edge operators (`[a, b] >> [c, d]`) — use explicit node-to-node
edges instead (the `diagrams` library may reject grouped expressions with a
`TypeError`) · Use emoji or Unicode glyphs in chart labels — keep labels
ASCII-safe for portability across container fonts.

## Scope Exclusions

Does NOT: produce Mermaid diagrams · generate Bicep/Terraform · create ADRs ·
deploy resources.

## Scripts

`scripts/diagram_io.py` (shared PNG+SVG output helper — import this from every generator) ·
`scripts/generate_diagram.py` (interactive diagram generation) ·
`scripts/multi_diagram_generator.py` (multi-type: process, ERD, timeline, wireframe) ·
`scripts/ascii_to_diagram.py` (ASCII art → diagram conversion) ·
`scripts/verify_installation.py` (prerequisites check)

## Reference Index

| File                                         | Content                                                             |
| -------------------------------------------- | ------------------------------------------------------------------- |
| `references/python-charts.md`                | Chart execution, design tokens, output standards                    |
| `references/waf-cost-charts.md`              | WAF pillar bar, cost donut & projection chart implementations       |
| `references/azure-components.md`             | Complete list of 700+ Azure diagram components                      |
| `references/common-patterns.md`              | Ready-to-use Python architecture patterns (3-tier, hub-spoke, etc.) |
| `references/business-process-flows.md`       | Workflow and swimlane diagram patterns                              |
| `references/entity-relationship-diagrams.md` | Database ERD patterns                                               |
| `references/integration-services.md`         | Integration service diagram patterns                                |
| `references/migration-patterns.md`           | Migration architecture patterns                                     |
| `references/sequence-auth-flows.md`          | Authentication flow sequence patterns                               |
| `references/timeline-gantt-diagrams.md`      | Project timeline and Gantt diagrams                                 |
| `references/ui-wireframe-diagrams.md`        | UI mockup and wireframe patterns                                    |
| `references/iac-to-diagram.md`               | Generate diagrams from Bicep/Terraform/ARM templates                |