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

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/)

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/)

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

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

Testing

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:

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
NEXT_PUBLIC_BACKEND_URL=...
NEXT_PUBLIC_ONLYOFFICE_BASE_URL=...

wolai-backend/.env:

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):

{
  "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" }