🎨 FlowCanvas: AI-Powered Diagram Tool

From prompt to professional diagrams — with real logos, not rectangles

---

🚀 Quick Start

Prerequisites: Node.js 20+ and pnpm 8+

# Install dependencies
pnpm install

# Start development server (always localhost:3000)
pnpm dev

Open http://localhost:3000 and start creating diagrams!

⚠️ Important: Always use pnpm (never npm or yarn). Server runs on localhost:3000 - check if it's already running.

---

✨ What Makes FlowCanvas Different?

Current AI diagram tools convert text → Mermaid code → generic rectangles. They can't access real logos (Docker, AWS, K8s), making diagrams look unprofessional.

FlowCanvas solves this:

• 🎯 AI → Real Logos: Uses Excalidraw's 100+ icon libraries
• 🧠 MCP-Powered: Model Context Protocol makes AI "library-aware"
• 🎨 Professional Output: Actual Docker, AWS, K8s icons, not boxes
• 🔒 Privacy-First: Local storage, data never leaves your device

---

🎯 Features

✅ Phase 1 Complete (Current)

• Infinite Canvas: Full Excalidraw drawing experience
• Auto-save: Diagrams saved to localStorage every second
• Dark Theme: Professional dark interface
• Export: PNG, SVG, JSON formats
• No Login Required: Start drawing immediately
• Persistent: Your work survives browser restarts
• Notes Panel: Markdown editor on the right with live preview and auto-save

🔜 Phase 2 (Coming Soon)

• Supabase authentication (optional cloud sync)
• Multiple diagrams with folder organization
• AI diagram generation (MCP-powered)
• Excalidraw library search (100+ icon packs)
• Templates & guided wizard

---

📋 Current Status

Week 1-2 Complete:

• ✅ Next.js 15 + React 19 + TypeScript setup
• ✅ Excalidraw integration (official best practices)
• ✅ localStorage persistence with auto-save
• ✅ Proper SSR handling (dynamic import)
• ✅ Clean component architecture
• ✅ Type-safe implementation

Next Steps (Week 3-4):

• Clone excalidraw-libraries repo
• Index top 20 libraries (AWS, Docker, K8s, databases, etc.)
• Create library search API (semantic + keyword)
• Build library panel UI with drag & drop
• Meilisearch integration for vector search

---

🏗️ Tech Stack

Frontend

• Framework: Next.js 15 (App Router) + Turbopack
• UI: React 19 + TypeScript 5
• Canvas: Excalidraw 0.18 (77k+ stars)
• Styling: TailwindCSS 4 + shadcn/ui
• State: Zustand + localStorage

Backend (Phase 2)

• Database: Supabase (PostgreSQL + Auth + Storage)
• Search: Meilisearch (vector search for libraries)
• AI: MCP Server (OpenAI, Claude, Ollama)

DevOps

• Package Manager: pnpm (enforced)
• Deployment: Vercel (frontend) + Railway (backend)
• Version Control: Git + GitHub

---

📂 Project Structure

flow/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── page.tsx             # Landing page with canvas
│   │   ├── layout.tsx           # Root layout
│   │   └── globals.css          # Global styles
│   ├── components/
│   │   ├── ExcalidrawWrapper.tsx  # Main canvas component (with CSS)
│   │   └── ExcalidrawCanvas.tsx   # Legacy component
│   └── lib/
│       └── storage.ts           # localStorage utilities (1s debounce)
├── .github/
│   └── copilot-instructions.md  # Full project specification
├── public/                       # Static assets
├── SETUP.md                      # Detailed setup guide
├── TROUBLESHOOTING.md            # Common issues & fixes
└── package.json

---

🛠️ Development

Available Scripts

pnpm dev          # Start dev server (localhost:3000)
pnpm build        # Build for production
pnpm start        # Start production server
pnpm lint         # Run ESLint

Key Development Rules

1. Package Manager: Always use pnpm (never npm or yarn)
2. Dev Server: Runs on localhost:3000 - check if already running
3. Dynamic Import: Excalidraw must use dynamic(() => import(...), { ssr: false })
4. CSS Import: Import @excalidraw/excalidraw/index.css in wrapper component
5. Types: Use proper TypeScript types from @excalidraw/excalidraw/types

---

🎨 Usage

Getting Started

1. Open http://localhost:3000
2. Draw on the left, write notes on the right (drag the splitter to resize)
3. Your work auto-saves every second (canvas + notes)
4. Close browser - diagram and notes persist in localStorage
5. Export: Click menu (☰) → Export as PNG/SVG/JSON

Keyboard Shortcuts

• V - Selection tool
• R - Rectangle
• D - Diamond
• O - Ellipse
• A - Arrow
• L - Line
• T - Text
• Ctrl/Cmd + Z - Undo
• Ctrl/Cmd + Shift + Z - Redo
• Ctrl/Cmd + D - Duplicate

---

🎯 Roadmap

Phase 1: Foundation ✅ (Weeks 1-2)

• Next.js + Excalidraw integration
• localStorage auto-save (1s debounce)
• Dark theme
• Export functionality
• Proper TypeScript types
• SSR handling

Phase 2: Cloud + Auth (Weeks 5-8)

• Supabase project setup
• Email + OAuth authentication (Google, GitHub)
• Multiple diagrams support
• Folders & organization
• Cloud sync
• Migration: localStorage → Supabase

Phase 3: AI Generation (Weeks 9-12)

• MCP Server (stdio transport)
• Index Excalidraw libraries (AWS, Docker, K8s)
• Meilisearch vector search
• AI prompt → diagram generation
• Template system
• Multi-LLM support (GPT-4, Claude, Ollama)

---

� Privacy & Data

• Local-First: All diagrams stored in browser localStorage (5-10MB limit)
• No Tracking: No analytics or telemetry (Phase 1)
• No Server: Data never leaves your device (Phase 1)
• Optional Cloud: Phase 2 adds Supabase with full user control

---

📖 Documentation

• SETUP.md - Detailed setup and usage guide
• TROUBLESHOOTING.md - Common issues and solutions
• .github/copilot-instructions.md - Full project specification

---

🔗 Resources

Official Documentation

• Excalidraw Docs - Canvas API reference
• Next.js Docs - Framework documentation
• Model Context Protocol - MCP specification

Reference Implementations

• Excalidraw Libraries - 100+ icon packs
• Excalidraw Next.js Example
• Eraser.io Clone - Feature inspiration

---

🤝 Contributing

Currently in early development (Phase 1). Contribution guidelines coming in Phase 2!

---

🙏 Acknowledgments

• Excalidraw - The amazing drawing library
• Eraser.io - Feature inspiration
• Daily Dose DS - Design inspiration
• GitHub Copilot - AI pair programming assistant

---

📄 License

MIT License - See LICENSE file for details

---

Built with ❤️ using Next.js, React, and Excalidraw