Add architecture diagram generator and docs

.claude/skills/architecture-diagram/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: architecture-diagram
+description: Generate architecture diagrams for documentation using matplotlib.
+version: 1.0.0
+author: OK Code
+tags:
+  - diagrams
+  - documentation
+  - architecture
+  - visualization
+tools:
+  - terminal
+  - filesystem
+triggers:
+  - use when the user asks for an architecture diagram
+  - use when the user wants to visualize system components or data flow
+  - use when a README needs a visual architecture overview
+  - use when the user says "generate diagram" or "architecture diagram"
+---
+
+# Architecture Diagram Generator
+
+## When to use this skill
+
+- When the user asks for an architecture diagram, system diagram, or component visualization.
+- When updating READMEs that would benefit from visual architecture documentation.
+- When comparing architectural alternatives visually (like the telemetry-architecture-comparison pattern).
+- When the user wants to visualize data flow, package dependencies, or tech stack layers.
+
+## What this skill does
+
+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.
+
+## Implementation
+
+### Step 1: Identify the diagram type
+
+Determine which diagram pattern fits the request:
+
+| Pattern | When to use | Example |
+|---------|-------------|---------|
+| **High-level architecture** | Full system overview with all components | `high-level-architecture.png` |
+| **Request/event flow** | Show how data moves through a pipeline | `server-request-flow.png` |
+| **Package dependencies** | Show import/dependency relationships | `package-dependencies.png` |
+| **Event flow** | Show event sourcing or pub/sub patterns | `orchestration-event-flow.png` |
+| **Tech stack** | Layered technology overview | `tech-stack.png` |
+| **Architecture comparison** | Compare N alternatives with scores | telemetry-style comparison grid |
+
+### Step 2: Use or extend the generator script
+
+The diagram generator lives at `scripts/generate-architecture-diagrams.py`. It provides reusable primitives:
+
+```python
+from generate_architecture_diagrams import (
+    draw_box,      # Rounded colored rectangle with label + sublabel
+    draw_arrow,    # Styled arrow with optional label and curve
+    draw_boundary, # Dashed service/group boundary
+    draw_badge,    # Colored score circle
+    new_fig,       # Create a new figure with standard theme
+    save,          # Save to assets/diagrams/
+    THEME,         # Consistent color palette
+    Box, Arrow,    # Dataclasses for components
+)
+```
+
+**To add a new diagram**, add a new `generate_*()` function to the script following the existing patterns, then call it from `main()`.
+
+**To create a standalone diagram**, write a new Python script that imports the primitives or copies the pattern.
+
+### Step 3: Generate the PNG
+
+```bash
+# Ensure matplotlib is available (use a venv if system Python is externally-managed)
+python3 -m venv /tmp/diag-venv 2>/dev/null
+/tmp/diag-venv/bin/pip install matplotlib 2>/dev/null
+/tmp/diag-venv/bin/python scripts/generate-architecture-diagrams.py
+```
+
+Output lands in `assets/diagrams/`. Reference from markdown as:
+```markdown
+![Alt text](assets/diagrams/diagram-name.png)
+```
+
+### Step 4: Embed in README
+
+Add diagram references to the relevant README.md using relative paths. Place diagrams immediately after the section heading they illustrate.
+
+## Visual language reference
+
+### Color palette (THEME dict)
+
+| Role | Color | Hex | Use for |
+|------|-------|-----|---------|
+| Client | Blue | `#4A90D9` | UI, browser, external clients |
+| Server | Green | `#2ECC71` | Server components, orchestration |
+| Provider | Orange | `#E67E22` | External provider processes |
+| Contracts | Purple | `#9B59B6` | Shared type/schema packages |
+| Shared | Light blue | `#3498DB` | Shared runtime utilities |
+| Storage | Amber | `#F39C12` | Persistence, checkpoints |
+| External | Gray | `#95A5A6` | External/third-party processes |
+| Desktop | Dark gray | `#34495E` | Desktop/Electron shell |
+
+### Arrow styles
+
+| Style | Color | Meaning |
+|-------|-------|---------|
+| Solid green | `arrow_ws` | WebSocket connection |
+| Solid orange | `arrow_stdio` | JSON-RPC stdio pipe |
+| Solid purple | `arrow_event` | Event stream / push |
+| Dashed | any | Import / dependency reference |
+
+### Component primitives
+
+- **Box**: `Box(x, y, w, h, label, color, sublabel=...)` — rounded rectangle with centered text
+- **Arrow**: `Arrow(x1, y1, x2, y2, label, color, curve=0.0)` — directed arrow, optional arc
+- **Boundary**: `draw_boundary(ax, x, y, w, h, label, color)` — dashed group rectangle
+- **Badge**: `draw_badge(ax, x, y, text, color)` — small colored circle with score
+
+## Best practices
+
+- Keep diagrams focused: one concept per diagram, not everything in one image.
+- Use the THEME palette consistently across all diagrams for visual coherence.
+- Place labels on arrows only when the connection type is ambiguous.
+- Use sublabels for technology annotations (e.g., "React/Vite", "effect/Schema").
+- For comparison diagrams, use green badges for recommended (score >= 30), amber for acceptable (>= 22), red for discouraged (< 22).
+- Always run the generator and verify the PNG visually before embedding in docs.
+- Output to `assets/diagrams/` — never inline base64 images in markdown.
+- Diagrams should be self-explanatory without reading surrounding text.

README.md

@@ -10,6 +10,11 @@ React client (`apps/web`) that renders live orchestration events and session sta
 
 ### High-level flow
 
+![OK Code System Architecture](assets/diagrams/high-level-architecture.png)
+
+<details>
+<summary>Mermaid source (text fallback)</summary>
+
 ```mermaid
 flowchart LR
   User["Developer"] --> UI["apps/web (React/Vite)"]
@@ -23,6 +28,16 @@ flowchart LR
   Shared --> UI
 ```
 
+</details>
+
+### Server request flow
+
+![Server Request Flow](assets/diagrams/server-request-flow.png)
+
+### Package dependencies
+
+![Package Dependencies](assets/diagrams/package-dependencies.png)
+
 ### Component responsibilities
 
 - `apps/server`
@@ -121,8 +136,14 @@ bun --filter @okcode/contracts typecheck
 | Validate TypeScript       | `bun run typecheck`              | no compile errors                                | all package typechecks pass                            |
 | Run tests                 | `bun run test`                   | Vitest suites execute                            | exit code 0, no failing tests                          |
 
+### Technology stack
+
+![Technology Stack](assets/diagrams/tech-stack.png)
+
 ## 5) Runtime behavior (what happens during a session)
 
+![Orchestration Event Flow](assets/diagrams/orchestration-event-flow.png)
+
 1. Web UI opens WebSocket and subscribes to orchestration events.
 2. UI submits user action to a `NativeApi` endpoint in `wsServer.ts`.
 3. Server dispatches the request through `providerManager`.