mnote/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

MNOTE is a knowledge management system combining Notion-like block documents, mind mapping, and AI-powered productivity tools. Built as a hybrid web/desktop application with local-first capabilities.

**Tech Stack:**
- Frontend: Next.js 16 (App Router), React 19, BlockNote editor
- Backend: FastAPI + Celery (Python)
- Desktop: Electron with embedded Next.js standalone
- Database: Supabase (PostgreSQL), migrating to Convex for some features
- AI: Tool-based agent system with 30+ built-in tools

## Development Commands

### Quick Start
```bash
npm run desktop:hot          # Start frontend + backend + Celery (recommended)
npm run desktop:local        # Local-only mode (offline)
npm run desktop              # Production desktop mode
```

### Frontend Only (wolai-frontend/)
```bash
pnpm dev                     # Next.js dev server on port 3000
pnpm build                   # Production build
pnpm start                   # Start production server
pnpm lint                    # ESLint check
pnpm test                    # Run Vitest unit tests
```

### Backend Only (wolai-backend/)
```bash
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000    # FastAPI dev server
celery -A app.workers.celery_app worker --loglevel=info  # Celery worker
```

### Desktop Build
```bash
npm run build:desktop:next   # Build Next.js standalone to desktop-electron/desktop-next/
npm run dist:win             # Build Windows NSIS installer
```

### Testing
```bash
cd pw-tests/scripts
python e2e_mindmap_sync.py   # Run E2E test
```

## Architecture

### Directory Structure
```
wolai-frontend/              # Main Next.js frontend (ACTIVE - use this)
├── src/
│   ├── app/                 # Next.js App Router
│   │   ├── (app)/           # Main app layout (sidebar + content)
│   │   ├── (auth)/          # Auth pages
│   │   ├── api/             # API routes (BFF pattern)
│   │   ├── documents/[id]/  # Document pages
│   │   └── mindmap/         # Mindmap pages
│   ├── components/
│   │   ├── editor/          # Editor components (BlockNote, blocks)
│   │   └── sidebar/         # File tree navigation
│   ├── lib/
│   │   ├── ai-agent/        # AI agent runtime & tools
│   │   ├── supabase/        # Supabase client wrappers
│   │   └── mindmap/         # Mindmap storage/logic
│   └── store/               # Zustand state stores
wolai-backend/               # FastAPI backend
├── app/
│   ├── main.py              # FastAPI entry point
│   ├── routers/             # API routes
│   ├── services/            # Business logic
│   └── workers/             # Celery tasks
desktop-electron/            # Electron wrapper
supabase/                    # Database migrations
```

**WARNING:** Root `src/` directory may be legacy/mirror. Always work in `wolai-frontend/src/` for frontend changes.

### Key Patterns

**BFF (Backend for Frontend):** Next.js API routes handle auth + Supabase queries. Frontend never talks directly to Supabase (except via client library).

**AI Agent System:** Tool-based architecture with execution loop, SSE streaming, and permission model (read/write). See `wolai-frontend/src/lib/ai-agent/`.

**Desktop + Web Parity:** Same Next.js codebase serves both. Desktop uses embedded server with runtime config override (`window.__MNOTE_RUNTIME_CONFIG__`).

**Mindmap First-Class:** Stored as structured JSON, not just visualization. Supports node refs (attachments, URLs with page numbers), AI expansion.

## Environment Configuration

### Required Variables

**wolai-frontend/.env.local:**
```bash
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
NEXT_PUBLIC_BACKEND_URL=...
NEXT_PUBLIC_ONLYOFFICE_BASE_URL=...
```

**wolai-backend/.env:**
```bash
SUPABASE_URL=...
SUPABASE_SERVICE_ROLE_KEY=...
REDIS_URL=redis://localhost:6379/0
FRONTEND_URL=http://localhost:3000
```

**AI Configuration (ai.md or env):**
```
apikey: sk-xxx
https://api.openai.com/v1
gpt-4
```

**Desktop (auto-generated in data/electron/config.json):**
```json
{
  "networkMode": "remote-client|local|tunnel|auto",
  "supabaseUrl": "...",
  "backendUrl": "..."
}
```

## Coding Conventions

- **File encoding:** UTF-8, Chinese comments allowed
- **Indentation:** 2 spaces (TS/TSX), 4 spaces (Python)
- **Naming:** PascalCase for components (`MindmapBlock.tsx`), `useXxx` for hooks, `*.test.ts(x)` for tests
- **Imports:** Use `@/` alias for absolute imports
- **Commits:** Version tags (`0.1.13 ...`) or conventional commits (`feat(mindmap):`, `fix:`, `chore:`)

## Key Files for Understanding

- `wolai-frontend/src/app/layout.tsx` - Root providers
- `wolai-frontend/src/lib/ai-agent/runtime/runAgent.ts` - AI agent engine
- `wolai-frontend/src/lib/ai-agent/tools/builtins/registryBuiltins.ts` - All AI tools
- `wolai-frontend/src/components/editor/document-content.tsx` - Editor core
- `wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx` - Mindmap UI
- `desktop-electron/main.js` - Desktop entry point
- `scripts/desktop-hot.js` - Dev orchestration
- `AGENTS.md` - Project guidelines (Chinese)
- `CODE_INDEX.md` - Complete code map (Chinese)

## Important Notes

- Never commit API keys or tokens
- Use existing ESLint/Vitest configurations
- Desktop data stored in `<install_dir>/data/` (portable)
- Supabase local: see `supabase.md` for ports/URLs
- Route directories contain `()` and `[]` - use `-LiteralPath` in PowerShell

## AI Agent Tool Development

When adding new AI capabilities, register tools in `wolai-frontend/src/lib/ai-agent/tools/builtins/`. Tools are organized by scope:
- **Global:** search_web, docs_search/read
- **Mindmap:** mindmap_get, mindmap_apply_ops
- **Document:** doc_get, doc_insert_blocks
- **OnlyOffice:** oo_get_selection, oo_replace_selection

Permission model: `{ read: "allow" | "confirm", write: "allow" | "confirm" }`