refactor: migrate Builder & Knowledge Graph to React Flow + dependency refresh

README.md

@@ -21,9 +21,9 @@ Toolbox is a self-hosted web app that brings together everything you need to pre
 |---------|-------------|
 | 🤖 **AI Learning Chat** | Session-based chat with 4 AI personas (Socratic, ELI5, Strict, Devil's Advocate), topic-specific starter prompts, and concept map generation |
 | 📖 **Knowledge Guide** | 7-pillar structured library with AI-assisted Commit flow to save learnings from chat sessions |
-| 🎨 **Architecture Builder** | Drag-and-drop whiteboard with 20+ components, bezier connections, templates, and AI design verification |
+| 🎨 **Architecture Builder** | React Flow-powered whiteboard with 25+ components, drag-to-connect anchors, minimap, multi-select, templates, and AI design verification |
 | 📚 **Flashcards + SRS** | SM-2 spaced repetition system with per-deck settings, card browser, deck stats, and a study activity heatmap |
-| 🕸️ **Knowledge Graph** | Interactive prerequisite map of ~60 system design concepts with a live SM-2 retention heatmap, readiness filters, curated learning tracks, and deep links into Guide, Builder, and Flashcards |
+| 🕸️ **Knowledge Graph** | Layered prerequisite map of ~60 system design concepts (React Flow + dagre) with a live SM-2 retention heatmap, lineage highlighting, readiness filters, curated learning tracks, and deep links into Guide, Builder, and Flashcards |
 | 🧱 **Adaptive Remediation** | Fail an advanced card and the SRS engine detects shaky foundations, then queues the prerequisite cards into your next review session |
 | 🧮 **BotE Calculator** | Back-of-the-envelope sizing sandbox: live QPS/storage/cache/bandwidth/hardware math, scenario presets, an interactive latency cheat-sheet with a budget composer, AI "Audit My Math", and 1-click Markdown export |
 | 🧠 **Feynman Simulator** | Voice-enabled Feynman technique: explain a concept, get structured AI feedback on gaps |
@@ -123,7 +123,7 @@ All user data lives in a single SQLite file — back it up by copying that file.
 
 ## 🛠️ Tech Stack
 
-React 19 · Vite · React Router · Zustand · Vanilla CSS · d3-force · Node.js · Express · SQLite (`better-sqlite3`) · Vercel AI SDK (Gemini / Claude / OpenAI / BYOM) · Docker
+React 19 · Vite · React Router · Zustand · React Flow (`@xyflow/react`) · dagre · Vanilla CSS · Node.js · Express · SQLite (`better-sqlite3`) · Vercel AI SDK (Gemini / Claude / OpenAI / BYOM) · Docker
 
 ---
 

docs/AGENTS.md

@@ -17,8 +17,9 @@
 | Layer | Choice | Why |
 |-------|--------|-----|
 | Frontend | React 19 + Vite | Established in project |
-| Routing | React Router DOM v6 | Established in project |
+| Routing | React Router DOM v7 | Established in project |
 | State | Zustand (persisted stores) | Established in project |
+| Diagrams | React Flow (`@xyflow/react`) + dagre | Whiteboard canvas + knowledge-graph layout |
 | Styling | **Vanilla CSS only** | See CSS rules below |
 | Icons | `lucide-react` only | Consistent icon set |
 | Backend | Node.js + Express | Simple, matches dev experience |
@@ -242,3 +243,7 @@ The Vite proxy config in `vite.config.js` forwards `/api/*` to the backend autom
 5. **Mobile detection**: Don't use CSS-only responsive tricks for conditional rendering. Use the `isMobile` state pattern (window resize listener) that's established in each page component.
 
 6. **Toast notifications**: Use `addToast({ type: 'success'|'error'|'info', message: '...' })` from `useAppStore` for user feedback. Never use `alert()`.
+
+7. **Two board shapes**: The app store holds whiteboard state in the React Flow shape (`position: {x,y}`, `data: {...}`, `source`/`target`). The database, the templates, and the server keep the legacy shape (`x`/`y`, `from`/`to`, anchors). Convert ONLY at the boundaries with `src/components/builder/boardModel.js` — never persist the React Flow shape.
+
+8. **Global `svg { max-width: 100% }` reset**: React Flow's edge SVGs collapse to zero width under it. The `.react-flow svg { max-width: none }` override in `index.css` protects them — keep it if you touch the reset.

docs/architecture.md

@@ -60,15 +60,16 @@ Toolbox is a **self-contained, single-binary-deployable** web application with n
 | Layer | Technology | Version | Role |
 |-------|-----------|---------|------|
 | **Frontend Framework** | React | 19 | UI rendering |
-| **Build Tool** | Vite | 6 | Dev server, bundler |
-| **Routing** | React Router DOM | 6 | Client-side routing |
-| **State Management** | Zustand | 4 | Global state (persisted) |
+| **Build Tool** | Vite | 8 | Dev server, bundler |
+| **Routing** | React Router DOM | 7 | Client-side routing |
+| **State Management** | Zustand | 5 | Global state (persisted) |
+| **Diagrams** | React Flow (`@xyflow/react`) + dagre | 12 / 3 | Whiteboard canvas + layered knowledge-graph layout |
 | **Styling** | Vanilla CSS | — | CSS Variables design system |
 | **Icons** | lucide-react | — | SVG icon library |
 | **Markdown** | react-markdown + remark-gfm + KaTeX | — | Rendered AI responses |
-| **Backend** | Node.js + Express | 18+ / 5 | API server |
-| **Database** | better-sqlite3 (SQLite) | — | Synchronous SQLite bindings |
-| **AI Client** | Google Generative AI SDK | — | Gemini API integration |
+| **Backend** | Node.js + Express | 22+ / 5 | API server |
+| **Database** | better-sqlite3 (SQLite) | 13 | Synchronous SQLite bindings |
+| **AI Client** | Vercel AI SDK | — | Gemini / Claude / OpenAI / BYOM integration |
 | **Container** | Docker (Alpine Linux) | — | Production container |
 | **Testing** | Vitest + React Testing Library | — | Unit and integration tests |
 
@@ -113,7 +114,8 @@ src/
 │   │   └── PillarNav.jsx      # Topic navigation within a pillar
 │   │
 │   ├── builder/             # Architecture whiteboard components
-│   │   ├── Canvas.jsx         # SVG canvas with pan/zoom and node/edge rendering
+│   │   ├── Canvas.jsx         # React Flow canvas (drag, connect, minimap, controls)
+│   │   ├── boardModel.js      # Persisted board shape ↔ React Flow converters + icon/color maps
 │   │   ├── Toolbox.jsx        # Component palette sidebar
 │   │   ├── BoardList.jsx      # Board tab bar
 │   │   └── TemplateGallery.jsx # Pre-built template picker

docs/user-guide.md

@@ -126,33 +126,32 @@ While viewing a topic, click **Ask AI** to open a contextual chat panel on the r
 
 ## Builder — Architecture Whiteboard
 
-The Builder (`/builder`) is an interactive canvas for practicing architecture diagrams.
+The Builder (`/builder`) is an interactive canvas for practicing architecture diagrams, powered by **React Flow**.
 
 ### Canvas
 
 - **Drag and drop** components from the left toolbox onto the canvas
-- **Connect** components by dragging from connection dots (appear on hover)
-- **Pan** by clicking and dragging the canvas background
-- **Zoom** with `⌘+`/`⌘-` or the zoom controls in the toolbar
+- **Connect** components by dragging between the anchor dots on any side of a card — any side connects to any side
+- **Remove** an edge with a single click on it, or select nodes/edges and press `Backspace`/`Delete`
+- **Pan** by dragging the canvas background; **zoom** with the mouse wheel or the on-canvas controls
+- **Multi-select** by dragging a selection box on empty canvas
+- The **minimap** (bottom-left) shows the whole board with category colors — click or drag it to jump around large diagrams
+- **Fit view** (the frame icon in the canvas controls) re-centers everything
 
 ### Component Library
 
 The toolbox organizes components by category:
 - **Compute** — Load Balancer, API Gateway, Microservice, Serverless Function, Background Worker, Message Queue, Event Bus, Stream Processor, Batch Processor, CDN/Edge Node
-- **Storage** — SQL Database, NoSQL Database, Cache (Redis), Object Storage (S3/GCS), Full-Text Search (Elasticsearch)
-- **Clients** — Web Client, Mobile Client
-- **Observability** — Monitoring & Alerting
+- **Storage** — SQL Database, NoSQL Database, Cache (Redis), Object Storage (S3/GCS), Full-Text Search (Elasticsearch), Vector Database
+- **Clients** — Web Client, Mobile Client, IoT Device, 3rd Party Service
+- **Resiliency** — Rate Limiter, Circuit Breaker, Retry/Backoff Handler, Load Shedder
+- **Observability** — Log Aggregator, Metrics Collector, Distributed Tracer
 
 ### Toolbar Features
 
 | Tool | Function |
 |------|----------|
-| **Select** | Click and drag nodes, resize canvas |
-| **Text** | Add free-form text labels |
-| **Arrow** | Draw directional arrows |
-| **Color** | Change component accent colors |
-| **Undo / Redo** | Step through changes |
-| **Zoom In / Out** | Adjust canvas zoom |
+| **Estimate** | Open the quick BotE Calculator modal |
 | **Templates** | Load pre-built architecture templates |
 | **Export** | Download board as a PNG image |
 | **Save** | Persist the board to the database (`⌘S`) |
@@ -278,7 +277,7 @@ Access it from the sidebar (`⌘6`) or navigate to `/interleaved`.
 
 ## Knowledge Graph
 
-The Graph page (`/graph`, `⌘7`) turns your flashcards and guide notes into an interactive **prerequisite map** of ~60 system design concepts, grouped by the 7 pillars. An edge means "learn this first" — for example *Consistent Hashing → Distributed KV Stores → Virtual Nodes*.
+The Graph page (`/graph`, `⌘7`) turns your flashcards and guide notes into an interactive **prerequisite map** of ~60 system design concepts, grouped by the 7 pillars. An edge means "learn this first" — for example *Consistent Hashing → Distributed KV Stores → Virtual Nodes*. A layered layout (dagre) places every prerequisite in an earlier column than its dependents, so learning always flows left → right. A minimap and canvas controls handle navigation on the large map.
 
 ### Retention Heatmap