🔮 KV-Graph

AI-Powered Diagram Editor — Transform ideas into beautiful, interactive flowcharts using natural language, images, or Mermaid code.

✨ Features

• 🤖 AI-Powered Generation — Generates complex diagrams from text prompts using Llama 3 (local browser) or Cloud AI.
• <EFBFBD>️ Vision-to-Diagram — Florence-2 powered analysis converts screenshots and sketches into editable layouts entirely in the browser.
• <EFBFBD>️ Unified Toolkit — A clean, consolidated toolbar for critical actions (Zoom, Layout, Pan/Select) keeps the canvas "void-like".
• 🗺️ MiniMap Overlay — Navigational aid for large diagrams, unobtrusively positioned in the bottom-right.
• 💡 Smart Guidance — Context-aware tips and rotation suggestions when looking at empty space.
• <EFBFBD> Theme-Aware Code Editor — Monaco editor that automatically syncs with your Light/Dark aesthetic.
• 🎨 "Void" Aesthetic — Premium glassmorphism design with deep blur effects and cinematic transitions.

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or pnpm
• WebGPU-compatible browser (Chrome 113+, Edge) for In-Browser AI

Installation

# Clone the repository
git clone https://github.com/your-username/kv-graph.git
cd kv-graph

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:5173 in your browser.

<EFBFBD> AI Configuration

KV-Graph supports a Local-First AI architecture, running powerful models directly in your browser via WebGPU.

🌐 In-Browser Mode (Privacy First)

Runs entirely on your device. No data leaves your machine.

Capability	Model	Technology
Text Generation	Llama-3-8B-Instruct	WebLLM (WebGPU)
Vision Analysis	Florence-2-base	Transformers.js (ONNX)

Note: First-time load requires downloading model weights (~4GB total).

☁️ Cloud Mode (Optional)

Connect to external providers for enhanced capabilities.

Provider	Model	API Key Required
OpenAI	GPT-4 Vision	✅
Google Gemini	Gemini Pro Vision	✅
Ollama	Custom	Local URL

Configure your AI provider in Settings (⚙️ icon).

📁 Project Structure

kv-graph/
├── src/
│   ├── components/        # React components
│   │   ├── nodes/         # Custom React Flow nodes
│   │   ├── edges/         # Custom React Flow edges
│   │   ├── editor/        # Monaco Code Editor
│   │   └── ui/            # UI Kit (Glassware)
│   ├── hooks/             # Custom React hooks
│   ├── lib/               # Core Logic
│   │   ├── aiService.ts   # AI Orchestrator
│   │   ├── webLlmService.ts # Local LLM Engine
│   │   ├── visionService.ts # Local Vision Engine
│   │   └── layoutEngine.ts # Dagre Auto-Layout
│   ├── pages/             # Route pages
│   ├── store/             # Zustand Global State
│   │   ├── flowStore.ts     # Combined Flow State
│   │   └── settingsStore.ts # AI & Theme Config
│   ├── styles/            # Tailwind Global Styles
│   └── types/             # TypeScript interfaces
├── public/                # Static assets & Models
└── Configuration files

🛠️ Tech Stack

Category	Technology
Framework	React 19 + TypeScript
Build Tool	Vite 7
Styling	Tailwind CSS 4
AI Inference	WebLLM (WebGPU) + Transformers.js
Diagramming	React Flow (XY Flow)
Code Editor	Monaco Editor (Theme Aware)
State	Zustand
Icons	Lucide React

📤 Export Formats

Format	Description
PNG	High-resolution raster image (3x pixel ratio)
JPG	Compressed image format
SVG	Vector graphics (scalable)
JSON	Full diagram data (nodes, edges, metadata)
Mermaid	Mermaid.js code for use elsewhere
React	Complete React component with React Flow

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl/⌘ + S	Save diagram
Ctrl/⌘ + E	Export diagram
Ctrl/⌘ + Z	Undo
Ctrl/⌘ + Shift + Z	Redo
Delete/Backspace	Delete selected node
Escape	Deselect / Close panel

🎨 Theming

KV-Graph features a premium glassmorphism design with:

• Dark Mode — Deep void backgrounds with subtle gradients
• Light Mode — Clean, minimal aesthetics
• Glass Panels — Frosted glass effects with blur
• Smooth Animations — Cinematic transitions

📜 Scripts

# Development
npm run dev          # Start dev server with HMR

# Production
npm run build        # Build for production
npm run preview      # Preview production build

# Code Quality
npm run lint         # Run ESLint

🗺️ Roadmap

• Undo/Redo history
• Real-time collaboration
• Custom node shapes
• Template library
• API for programmatic diagram generation
• Plugin system

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

• React Flow — Powerful diagram library
• Mermaid.js — Diagram syntax inspiration
• Ollama — Local AI inference
• Tailwind CSS — Utility-first styling

---

Made with ❤️ by vndangkhoa