Skip to content

Commit 6344975

Browse files
BunsDevBunsDev
committed
Add architecture diagram generation skill
1 parent bc038a1 commit 6344975

1 file changed

Lines changed: 129 additions & 0 deletions

File tree

  • .agents/skills/architecture-diagram

‎.agents/skills/architecture-diagram/SKILL.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
name: architecture-diagram
3+
description: Generate architecture diagrams for documentation using matplotlib.
4+
version: 1.0.0
5+
author: OK Code
6+
tags:
7+
- diagrams
8+
- documentation
9+
- architecture
10+
- visualization
11+
tools:
12+
- terminal
13+
- filesystem
14+
triggers:
15+
- use when the user asks for an architecture diagram
16+
- use when the user wants to visualize system components or data flow
17+
- use when a README needs a visual architecture overview
18+
- use when the user says "generate diagram" or "architecture diagram"
19+
---
20+
21+
# Architecture Diagram Generator
22+
23+
## When to use this skill
24+
25+
- When the user asks for an architecture diagram, system diagram, or component visualization.
26+
- When updating READMEs that would benefit from visual architecture documentation.
27+
- When comparing architectural alternatives visually (like the telemetry-architecture-comparison pattern).
28+
- When the user wants to visualize data flow, package dependencies, or tech stack layers.
29+
30+
## What this skill does
31+
32+
Generates publication-quality PNG architecture diagrams using Python + matplotlib. Diagrams use a consistent visual language: colored rounded boxes for components, styled arrows for data flow, dashed boundaries for service groups, and score badges for comparisons.
33+
34+
## Implementation
35+
36+
### Step 1: Identify the diagram type
37+
38+
Determine which diagram pattern fits the request:
39+
40+
| Pattern | When to use | Example |
41+
| --------------------------- | ---------------------------------------- | ------------------------------- |
42+
| **High-level architecture** | Full system overview with all components | `high-level-architecture.png` |
43+
| **Request/event flow** | Show how data moves through a pipeline | `server-request-flow.png` |
44+
| **Package dependencies** | Show import/dependency relationships | `package-dependencies.png` |
45+
| **Event flow** | Show event sourcing or pub/sub patterns | `orchestration-event-flow.png` |
46+
| **Tech stack** | Layered technology overview | `tech-stack.png` |
47+
| **Architecture comparison** | Compare N alternatives with scores | telemetry-style comparison grid |
48+
49+
### Step 2: Use or extend the generator script
50+
51+
The diagram generator lives at `scripts/generate-architecture-diagrams.py`. It provides reusable primitives:
52+
53+
```python
54+
from generate_architecture_diagrams import (
55+
draw_box, # Rounded colored rectangle with label + sublabel
56+
draw_arrow, # Styled arrow with optional label and curve
57+
draw_boundary, # Dashed service/group boundary
58+
draw_badge, # Colored score circle
59+
new_fig, # Create a new figure with standard theme
60+
save, # Save to assets/diagrams/
61+
THEME, # Consistent color palette
62+
Box, Arrow, # Dataclasses for components
63+
)
64+
```
65+
66+
**To add a new diagram**, add a new `generate_*()` function to the script following the existing patterns, then call it from `main()`.
67+
68+
**To create a standalone diagram**, write a new Python script that imports the primitives or copies the pattern.
69+
70+
### Step 3: Generate the PNG
71+
72+
```bash
73+
# Ensure matplotlib is available (use a venv if system Python is externally-managed)
74+
python3 -m venv /tmp/diag-venv 2>/dev/null
75+
/tmp/diag-venv/bin/pip install matplotlib 2>/dev/null
76+
/tmp/diag-venv/bin/python scripts/generate-architecture-diagrams.py
77+
```
78+
79+
Output lands in `assets/diagrams/`. Reference from markdown as:
80+
81+
```markdown
82+
![Alt text](assets/diagrams/diagram-name.png)
83+
```
84+
85+
### Step 4: Embed in README
86+
87+
Add diagram references to the relevant README.md using relative paths. Place diagrams immediately after the section heading they illustrate.
88+
89+
## Visual language reference
90+
91+
### Color palette (THEME dict)
92+
93+
| Role | Color | Hex | Use for |
94+
| --------- | ---------- | --------- | -------------------------------- |
95+
| Client | Blue | `#4A90D9` | UI, browser, external clients |
96+
| Server | Green | `#2ECC71` | Server components, orchestration |
97+
| Provider | Orange | `#E67E22` | External provider processes |
98+
| Contracts | Purple | `#9B59B6` | Shared type/schema packages |
99+
| Shared | Light blue | `#3498DB` | Shared runtime utilities |
100+
| Storage | Amber | `#F39C12` | Persistence, checkpoints |
101+
| External | Gray | `#95A5A6` | External/third-party processes |
102+
| Desktop | Dark gray | `#34495E` | Desktop/Electron shell |
103+
104+
### Arrow styles
105+
106+
| Style | Color | Meaning |
107+
| ------------ | ------------- | ----------------------------- |
108+
| Solid green | `arrow_ws` | WebSocket connection |
109+
| Solid orange | `arrow_stdio` | JSON-RPC stdio pipe |
110+
| Solid purple | `arrow_event` | Event stream / push |
111+
| Dashed | any | Import / dependency reference |
112+
113+
### Component primitives
114+
115+
- **Box**: `Box(x, y, w, h, label, color, sublabel=...)` — rounded rectangle with centered text
116+
- **Arrow**: `Arrow(x1, y1, x2, y2, label, color, curve=0.0)` — directed arrow, optional arc
117+
- **Boundary**: `draw_boundary(ax, x, y, w, h, label, color)` — dashed group rectangle
118+
- **Badge**: `draw_badge(ax, x, y, text, color)` — small colored circle with score
119+
120+
## Best practices
121+
122+
- Keep diagrams focused: one concept per diagram, not everything in one image.
123+
- Use the THEME palette consistently across all diagrams for visual coherence.
124+
- Place labels on arrows only when the connection type is ambiguous.
125+
- Use sublabels for technology annotations (e.g., "React/Vite", "effect/Schema").
126+
- For comparison diagrams, use green badges for recommended (score >= 30), amber for acceptable (>= 22), red for discouraged (< 22).
127+
- Always run the generator and verify the PNG visually before embedding in docs.
128+
- Output to `assets/diagrams/` — never inline base64 images in markdown.
129+
- Diagrams should be self-explanatory without reading surrounding text.

0 commit comments

Comments
 (0)