🛰️ SOVERN MindMap Control Plane (v3.3)

Visual Control Plane for the AI-First One-Person Organization.

The SOVERN MindMap Control Plane is a high-performance orchestration tool designed for the "Solo Vibe Coder." It bridges the gap between structured mind-mapping and active project management, integrating a deterministic execution engine with native AI Agent connectivity.

---

🚀 Key Features

1. Multimodal Visualization (The 6 Views)

Switch seamlessly between six analytical dimensions. The MindMap and Diagram are React Flow canvases; Matrix, Timeline, Kanban and Outline are dedicated DOM views layered on top:

• 🕸️ MindMap Mode: Hierarchical canvas. Feedback boards get a cluster layout (area columns with card grids); generic graphs fall back to Dagre auto-layout.
• 🧭 Diagram Mode: Strict org-chart tree or dependency swimlanes (one lane per layer), orthogonal edges with arrows, plus a read-only presentation mode for demos and exports.
• 📊 Priority Matrix (2x2): Eisenhower quadrants (Do First / Schedule / Quick Wins / Backlog) with tinted backgrounds. Tickets render as compact chips positioned by Impact × Urgency (1-10); same-cell tickets stack with a "+N" expander.
• 📅 Timeline: Area lanes over a real time axis (ticket created date), day gridlines, greedy stacking on overlap.
• 📋 Kanban Board: Triage / Pending / Active / Done / Blocked columns with counts, search, area filters and drag-and-drop — dropping a card persists the status change back to feedback.jsonl via the dev-server API (POST /api/feedback/status → fb.mjs).
• ≡ Outline / Document: the graph as a linear, nested Markdown document (each root a # heading, descendants depth-indented bullets, DFS pre-order) with Copy + Save .md. A visual↔linear switch for writing/reading and the LMS workflow — read-only (the graph is edited on the canvas).

2. Deterministic AI-First PM Engine

• ⚡ Token Budgeting: Replaced traditional currency with AI Tokens. Costs roll up automatically from subtasks to parent projects.
• ⏳ Temporal Roll-Up: Automatic calculation of project phases based on earliest-start and latest-end dates of leaf nodes.
• 🤖 Agent-Native: Built-in MCP Server (Model Context Protocol) allows Hermes or Claude to read and mutate the graph programmatically.
• 🛰️ n8n Integration: Ready-to-use webhook infrastructure that triggers external automation on status changes.

3. Sovereign Infrastructure

• Local-First & Obsidian Ready: Native support for the .canvas format. Your "Control Plane" and "Second Brain" share a single source of truth.
• 🗂️ Project Tabs (multi-board, 2026-07-08): the canvas is multi-board — a top tab bar switches independent boards (create/rename/close; per-board persistence + undo history). Three tab kinds: user boards, the service «Design Review» board (DesOps artifacts land ONLY here, with a pending badge; stray artifact nodes are swept off user boards), and «board.canvas (live)» — a read-only live mirror of the repo feed (never persisted; the file is the source of truth). Legacy single-workspace content migrates into the "Main" board automatically and the legacy key is never deleted.
• mc_hub Feedback Bridge: Dev server serves /board.canvas from the mc_hub triage pipeline (path via SOVERN_BOARD env), polls it every 3s, and writes status changes back through fb.mjs — the board is a live two-way window into feedback.jsonl. With the boards registry present, the feed renders exclusively on its own «board.canvas (live)» tab.
• 🎨 Theming: Dark (cyberpunk neon) / Light (clean professional) / System modes with persistence. Upload W3C Design Tokens JSON (Figma / Style Dictionary export) to re-skin the entire app — colors live in CSS custom properties.
• 📖 Reading Mode: a one-click neuro-inclusive preset (orthogonal to dark/light) — swaps in the OpenDyslexic font (vendored, Latin and Cyrillic), opens up line/letter spacing, calms the canvas grid, and stops decorative motion (plus an always-on prefers-reduced-motion baseline). Persisted; no runtime CDN.
• 🖼️ PNG Export: One click exports the full graph (fit-to-content) in canvas views or a snapshot of Kanban/Matrix/Timeline.

4. Hand Editing (Edit Mode)

The app boots as a viewer of the live board; the first hand-edit enters Edit Mode, which freezes the 3s poll so your edits aren't clobbered (a banner shows the paused state; Done flushes a final save and resumes the live board).

• ⌨️ Keyboard authoring: Tab = child, Enter = sibling, F2 / double-click = rename, Delete = cascade-delete, Esc = clear.
• ↩️ Undo / Redo: Ctrl+Z / Ctrl+Y (zundo) — one step per structural edit; React-Flow churn never pollutes history.
• ✏️ Inline editing on the node itself, fold/collapse subtrees (+N badge), and copy/paste subtree (Ctrl+C / Ctrl+V, fresh ids).
• 🔷 Shape picker: select a node → pick from the 29-shape palette in the sidebar (Basic / Home AI-lab / Cloud groups); the node converts to that diagram shape in one undo step (works on any node, including hand-authored ones).
• 🧰 Drag-from-library: a persistent shape rail on the left edge of the MindMap canvas — drag a swatch onto the canvas to create a brand-new standalone shape node at the drop point (labelled with the shape kind, selected, one undo step; drop position preserved). Each swatch is a keyboard-accessible button — Tab to focus, Enter/Space (or click) adds the shape at the canvas center. MindMap-only; foreign drags ignored.
• 💾 Autosave to a separate workspace file (Tauri app-data / browser localStorage) — never writes board.canvas.

5. AI Canvas (prompt → diagram)

Describe a diagram in the prompt bar and an editable one appears on the same canvas — no separate tool windows. Tools are invisible backends; the canvas is the single surface.

• 🪄 Generation: prompt → LiteLLM gateway (dev-proxied at /llm; the key is injected server-side and never reaches the client bundle) → output normalized/repaired by extractCanvas → native JSON Canvas interchange (not Mermaid) → appended as one undoable Edit-Mode edit with dagre layout.
• 🔷 29 shapes (one SHAPE_KINDS source of truth, rendered via the shapeGeometry registry):
  • Basic (12): rectangle · rounded · decision · terminal · note · cylinder (datastore) · ellipse · parallelogram (I/O) · hexagon · cloud (service) · actor (user) · document.
  • Home AI-lab pack (14): server · gpu · workstation · laptop · storage · router · switch · firewall · wifi · model · agent · vector-store · gateway · container — lucide-icon shapes for diagramming a home AI lab (compute / networking / ML stack). The generation prompt has a scope-guard so they don't leak into ordinary flowcharts.
  • Cloud pack (3): aws · azure · gcp — vendored official monochrome brand marks (no runtime dep) for public-cloud architecture diagrams; the prompt scope-guards them like the home-lab pack.
• Needs the LiteLLM gateway running (canonical port in NAUTILUS/config/services.json; the proxy defaults to :4001, override with SOVERN_LLM_GATEWAY).

6. Learn Mode (step-through walkthroughs)

Turn any diagram into a cumulative, self-paced walkthrough — built for non-technical learners (the canvas materialises a concept step by step instead of dumping the whole schema at once). Enter via the 🎓 GraduationCap toolbar button; it's read-only (editor keys, dragging and selection are gated off).

• ▶️ Cumulative reveal: → / Space / ← reveal nodes one at a time, with the current node accent-ringed and the picture re-framed each step.
• 🗣️ Per-step narration: step order and a sentence of narration ride inside the node as mm:step / mm:note (carried through JSON Canvas like mm:shape); the AI generator fills them, otherwise the order falls back to a deterministic BFS from the graph roots.

7. Import & Export (draw.io interop + shareable artifacts)

• 📥 Import .drawio: load an existing draw.io file (compressed or "Edit Diagram" XML) — vertices, edges, labels and real coordinates are mapped onto the canvas; shapes best-effort-mapped to the shape vocabulary. Native DOMParser + DecompressionStream (no dependency).
• 📤 Export .drawio: serialize the canvas back to mxGraph XML — opens editable in real draw.io. The import↔export round-trip is proven by an integration test and verified in real draw.io.
• 🖼️ Export PNG / 🌐 Export HTML: a one-file interactive HTML (pan/zoom + dark/light toggle, captured in both themes) — a shareable diagram, no app or server needed.
• 🎬 Export Learn HTML: bake the Learn-mode walkthrough into a single self-contained .html (cumulative frames + narration + prev/next on a neutral background that reads on light and dark pages) — drop it into an <iframe> to embed a step-through in an LMS/course unit; it keeps working even if this app goes away.
• Every exported HTML references no external resources and escapes all untrusted labels/text.

---

🛠️ Tech Stack

• Core: Tauri 2.0 (Secure Rust Bridge)
• UI: React 19 + TypeScript + Vite 7
• Styling: Tailwind CSS v4 + CSS Custom Properties theming
• Graph Logic: @xyflow/react + Dagre (Auto-layout)
• State: Zustand
• Tests: Vitest

---

📦 Installation

# Clone the repository
cd sovern-mindmap

# Install dependencies
npm install

# Run Desktop version (Requires Rust)
npm run tauri dev

# Run Browser version (Safe Preview)
npm run dev

---

🔌 sovern-canvas MCP

The MCP server (src/mcp) exposes create_artifact_node and read_artifact_decisions so DesOps agents can drop generated UI variants onto the live canvas (:1420) and read back human approve/reject decisions. It ships as a separate build target, not part of the Vite/Tauri app bundle:

• Build once per checkout: npm run build:mcp — emits dist-mcp/ (gitignored; not committed, not produced by npm run dev/npm run build).
• Registration: the built server is registered in C:\telo\.mcp.json — re-run the build after a fresh clone or after editing anything under src/mcp/ before the tools will pick up changes.
• Runtime bridge: the canvas dev server (vite.config.ts) polls the same .sovern/artifact-inbox.jsonl / artifact-decisions.jsonl ledger every 2s via GET /api/artifacts, so artifact nodes created through the MCP tools appear on the canvas without a page reload, already reconciled with any prior decision (an artifact that was already approved/rejected in an earlier session re-ingests with that status, not pending).
• Decisions (2026-07-10): three verdicts — approved / rejected / deleted. Deleting an artifact node on the Design Review board writes a deleted tombstone; the feed filters latest-deleted artifacts, so they never resurrect. Approve+Export records a single ledger row (approved + variant_group + exportedTo) via /export.

---

📂 Project Structure

• /src/mcp — MCP Server implementation for AI agents.
• /src/store — Zustand store managing the "Global Brain" of the app.
• /src/components — KanbanBoard, MatrixView, TimelineView (DOM views), NodeSidebar, nodes/SOVERNNode.
• /src/utils/pmEngine.ts — Deterministic math for tokens and dates.
• /src/utils/layout.ts — Dagre auto-layout + feedback-board cluster layout.
• /src/utils/feedback.ts — Shared area/category/status palette + Priority Matrix quadrants.
• /src/ai — Prompt → diagram pipeline (LiteLLM client, extractCanvas, generateDiagram).
• /src/drawio — draw.io interop: import (inflate, drawioToCanvas, mxStyle) and export (canvasToDrawio, exportDrawio).
• /src/export — Self-contained artifact exporters: PNG, HTML, and Learn-HTML walkthroughs (captureCanvasSvg, htmlTemplate, learnHtmlTemplate, saveFile).
• AGENT_INTEGRATION.md — How to connect your agents.

---

Alexander (Solo Vibe Coder) · SOVERN v3.3 · Alpha Phase Complete