FlowCanvas AI Diagram Tool

An AI-powered diagram generation tool that creates professional diagrams with real logos and icons, not just generic rectangles.

Overview

FlowCanvas converts natural language prompts into professional diagrams using Excalidraw and Model Context Protocol (MCP). The core innovation is library-aware AI that can search and place actual SVG icons from 100+ Excalidraw libraries.

Key Technical Stack

**Frontend**: Next.js 14+ with TypeScript

**Canvas**: Excalidraw React component

**AI Integration**: MCP Server with OpenAI/Claude/Ollama

**Database**: Supabase PostgreSQL

**Authentication**: Supabase Auth

**Storage**: localStorage (anonymous) + Supabase (authenticated)

**Package Manager**: pnpm (exclusively)

Development Guidelines

Package Management

**CRITICAL: Always use pnpm, never npm or yarn**

Install dependencies: `pnpm install <package>`

Add dev dependency: `pnpm add -D <package>`

Run dev server: `pnpm dev`

Build: `pnpm build`

Development Server Rules

1. Dev server runs at `http://localhost:3000`

2. Check if server is running before starting new instance

3. Never create multiple dev servers

4. Use relative paths or explicit `http://localhost:3000` in development

Operational Constraints

Port 3000 is the standard development port

Avoid starting dev server unnecessarily (it's usually already running)

Never commit `package-lock.json` or `yarn.lock` files

Use `pnpm-lock.yaml` only

Architecture Decisions

Why Excalidraw Over Tldraw

100+ community library packs vs basic shapes

Native `.excalidrawlib` format for logos

77k+ GitHub stars (larger community)

Library ecosystem is the key differentiator

AI Library Awareness via MCP

**Implementation Flow:**

1. Index Excalidraw libraries → Clone repo, parse JSON, store in PostgreSQL + Meilisearch

2. Expose via MCP Server → Resources, Tools, Prompts

3. Inject available icons into AI system prompts

**MCP Architecture:**

```

Frontend (Next.js)

↓

MCP Client

↓

MCP Server (Node.js)

├─ Resources: library://catalog

├─ Tools: search_libraries(), generate_diagram()

└─ Prompts: system_diagram_generator

↓

LLM (GPT-4/Claude/Ollama)

↓

Excalidraw JSON with real logos

```

User Experience Strategy

Two-Mode System

**Mode 1: Anonymous (Local-Only)**

No login required

Auto-save to localStorage every 2 seconds

Single diagram limit

5MB storage maximum

Data never leaves device

Export to PNG/SVG/JSON available

**Mode 2: Authenticated (Cloud Sync)**

Unlimited diagrams

Cloud storage with Supabase

Access from any device

Organization features (folders, tags, search)

Version history

Collaboration (future)

Migration Flow

When anonymous users sign up:

1. Detect localStorage diagram

2. Create diagram record in Supabase

3. Migrate content to cloud

4. Clear localStorage

5. Show success confirmation

Feature Comparison

|---------|-----------|-------------------|-------------|

| Multi-device | No | Yes | Yes |

| Folders | No | Yes | Yes |

| Collaboration | No | No | Yes |

Implementation Instructions

Phase 1: MVP Foundation (Weeks 1-8)

**Weeks 1-2: Anonymous Mode**

1. Set up Next.js 14 + TypeScript project

2. Integrate Excalidraw React component

3. Implement localStorage auto-save (2-second debounce)

4. Add export functionality (PNG/SVG)

5. No authentication required

**Weeks 3-4: Library System**

1. Clone and index Excalidraw libraries repository

2. Parse library JSON files

3. Build search API (semantic + keyword matching)

4. Create searchable library panel UI

5. Implement drag-and-drop icon placement

**Weeks 5-6: MCP Server Setup**

1. Install `@modelcontextprotocol/sdk`

2. Configure stdio transport

3. Implement MCP Resources (catalog endpoint)

4. Create MCP Tools (search_libraries, generate_diagram)

5. Integrate OpenAI, Claude, and Ollama providers

**Weeks 7-8: AI Generation**

1. Engineer library-aware prompts

2. Develop smart positioning algorithm

3. Create AI dialog UI with progress indicators

4. Test with different LLM providers

Phase 2: Enhanced Features (Weeks 9-12)

**Week 9: Eraser.io-Style Features**

1. Implement split view (Canvas + Markdown editor)

2. Add bidirectional linking between notes and diagram elements

3. Support MDX format

**Week 10: Template System**

1. Create template categories (System Architecture, Data Flow, Network)

2. Build guided wizard for template selection

3. Enable tech stack selection

4. Generate diagrams from templates

**Week 11: Local LLM Integration**

1. Integrate Ollama

2. Support Llama 3.2 and DeepSeek-Coder

3. Enable fully offline operation

4. Zero API costs mode

**Week 12: Organization Features**

1. Implement folders and tags

2. Add search functionality

3. Create version history system

4. Build diagram management dashboard

Phase 3: Polish & Production (Weeks 13-16)

**Week 13: Real-time Collaboration**

1. WebSocket setup

2. Cursor tracking

3. Presence indicators

4. Conflict resolution

**Week 14: Performance Optimization**

1. Lazy load libraries

2. Implement caching strategies

3. Optimize bundle size

4. Add loading states

**Week 15: Educational Features**

1. Create interactive tutorials

2. Add example diagrams

3. Build template gallery

4. Documentation

**Week 16: Testing**

1. Unit tests for core functions

2. Integration tests for API

3. E2E tests for user flows

4. Performance testing

Real-time Collaboration

Current Implementation: BroadcastChannel (Active)

**Status: Working**

Real-time sync across browser tabs on same device

No server setup required

Uses native Browser API

Perfect for testing and demos

**Usage:**

1. Click "Live collaboration..." button

2. Click "Start session"

3. Copy generated link

4. Open link in another tab/window

5. Draw in one tab → See updates in real-time!

**Key Files:**

`src/lib/collaboration/BroadcastCollaborationManager.ts`

`src/components/ExcalidrawWrapper.tsx`

`src/components/CollaborationDialog.tsx`

**Limitations:**

Only works on same device (not across internet)

No persistence when all tabs close

Great for local testing

Future: Supabase Realtime (Production Ready)

**Features:**

Real-time sync across devices globally

Persistent connections

Presence tracking

Production scalability

**Setup Requirements:**

1. Create Supabase project

2. Configure environment variables

3. Enable Realtime in Supabase dashboard

4. Switch manager in `ExcalidrawWrapper.tsx`

Code Standards

TypeScript Best Practices

Use strict mode

Explicit return types for functions

Proper interface definitions

No `any` types unless absolutely necessary

React Patterns

Functional components only

Custom hooks for shared logic

Proper dependency arrays in useEffect

Memoization where appropriate

File Organization

```

src/

├── components/ # React components

├── lib/

│ ├── collaboration/ # Collaboration managers

│ ├── mcp/ # MCP server code

│ └── supabase.ts # Supabase client

├── app/ # Next.js app directory

└── types/ # TypeScript type definitions

```

Error Handling

localStorage Operations

Always wrap in try-catch blocks:

```typescript

try {

localStorage.setItem('key', JSON.stringify(data));

} catch (error) {

console.error('Storage failed:', error);

// Fallback logic

}

```

API Calls

Implement proper error boundaries and user feedback:

```typescript

const { data, error } = await supabase

.from('diagrams')

.insert(diagram);

if (error) {

toast.error('Failed to save diagram');

console.error(error);

return null;

}

```

MCP Server

Handle connection failures gracefully and provide fallback options.

Security Considerations

1. **Row Level Security (RLS)**: Enable on all Supabase tables

2. **API Keys**: Never commit to version control

3. **Input Validation**: Sanitize all user inputs

4. **XSS Protection**: Escape user-generated content

5. **Rate Limiting**: Implement for AI generation endpoints

Testing Strategy

Unit Tests

Library search functions

Auto-save logic

Migration utilities

MCP tool implementations

Integration Tests

Supabase operations

Authentication flows

Diagram CRUD operations

Library indexing

E2E Tests

Anonymous user flow

Sign-up and migration

Diagram creation

Collaboration sessions

Export functionality

Important Notes

**Never start multiple dev servers** - this is a critical constraint

**pnpm only** - converting npm/yarn commands is required

**localhost:3000** - hardcoded development URL

**Auto-save frequency** - 2-second debounce is optimal

**localStorage limit** - 5-10MB maximum

**Library indexing** - Run on startup or as background job

Common Pitfalls to Avoid

1. Using npm/yarn instead of pnpm

2. Starting duplicate dev servers

3. Committing wrong lock files

4. Skipping localStorage error handling

5. Not implementing proper RLS policies

6. Ignoring auto-save debouncing

7. Hard-coding API keys

8. Missing migration flows for anonymous users

Success Criteria

**MVP Success Metrics:**

User can create diagram without login

AI generates diagrams with real logos

Auto-save works reliably

Export functions correctly

BroadcastChannel collaboration works

**Production Success Metrics:**

Supabase authentication functional

Multi-device sync operational

100+ libraries indexed and searchable

Sub-5 second AI generation time

Zero data loss during migration

FlowCanvas AI Diagram Tool

FlowCanvas AI Diagram Tool

Overview

Key Technical Stack

Development Guidelines

Package Management

Development Server Rules

Operational Constraints

Architecture Decisions

Why Excalidraw Over Tldraw

AI Library Awareness via MCP

User Experience Strategy

Two-Mode System

Migration Flow

Feature Comparison

Implementation Instructions

Phase 1: MVP Foundation (Weeks 1-8)

Phase 2: Enhanced Features (Weeks 9-12)

Phase 3: Polish & Production (Weeks 13-16)

Real-time Collaboration

Current Implementation: BroadcastChannel (Active)

Future: Supabase Realtime (Production Ready)

Code Standards

TypeScript Best Practices

React Patterns

File Organization

Error Handling

localStorage Operations

API Calls

MCP Server

Security Considerations

Testing Strategy

Unit Tests

Integration Tests

E2E Tests

Important Notes

Common Pitfalls to Avoid

Success Criteria

Reviews (0)