CLAUDE.md git:20260428.3ef311eA

Immutable. This exact content never changes and is served at /api/v1/blob/1b10ebcc34782224.

# CLAUDE.md

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

## Project Overview

**zenstory** is an AI-assisted novel writing workbench with a conversational AI interface. Files (outlines, drafts, characters, lores) are the central unit, with AI conversations driving content generation.

**Architecture**: Monorepo with React frontend (apps/web) and FastAPI backend (apps/server). Three-panel layout: File tree (left), Editor (middle), AI Chat (right).

**Related Documentation**:
- `apps/server/agent/CLAUDE.md` - Detailed Agent system architecture (multi-agent workflow, tools, SSE events)

## Development Commands

### Backend (FastAPI/Python)

```bash
cd apps/server

# Install dependencies (first time only)
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Start backend server (port 8000)
python3 main.py

# Run specific Alembic migration
alembic upgrade head

# Create new migration
alembic revision --autogenerate -m "description"
```

### Frontend (React/Vite)

```bash
cd apps/web

# Install dependencies
pnpm install  # or npm install

# Start development server (port 5173)
pnpm dev  # or npm run dev

# Build for production
pnpm build

# Type-check + build
pnpm run build:typecheck

# Lint
pnpm lint
```

### Running Both Services

From project root (requires two terminals):
```bash
# Terminal 1: Backend
cd apps/server && source venv/bin/activate && python3 main.py

# Terminal 2: Frontend
cd apps/web && pnpm dev
```

### Database Migrations

The backend uses Alembic for database migrations:
- Migrations are in `apps/server/alembic/versions/`
- Configuration: `apps/server/alembic.ini`
- After schema changes: `alembic revision --autogenerate -m "description"` then `alembic upgrade head`

## Architecture Overview

### Backend (apps/server)

**Tech Stack**: FastAPI, SQLModel (Pydantic + SQLAlchemy), SQLite (dev) / PostgreSQL (production), Anthropic Claude API, LlamaIndex, ChromaDB

**Key Directories**:
- `main.py` - App entry point, registers all routers and middleware
- `api/` - API route handlers (auth, projects, files, versions, agent, chat, export, voice)
- `models/` - SQLModel database models (entities, file_model, file_version)
- `services/` - Business logic layer (file_version_service, snapshot_service, verification_service, export_service)
- `agent/` - AI Agent system (service.py, suggest_service.py, tools/, context/, schemas/)
- `database.py` - Database connection and session management
- `config/` - Configuration modules (logger, settings)

**Important**: The codebase uses a service layer pattern. Route handlers in `api/` should be thin and delegate business logic to `services/`.

### Frontend (apps/web)

**Tech Stack**: React 19, TypeScript, Vite, Tailwind CSS 4.x, Zustand, TanStack React Query, Tiptap editor, react-arborist (file tree)

**Key Directories**:
- `components/` - React components (Layout, FileTree, Editor, ChatPanel, MessageList, etc.)
- `contexts/` - React Context providers (AuthContext, ProjectContext, ThemeContext)
- `hooks/` - Custom hooks (useAgentStream, useVoiceInput, useExport)
- `lib/` - Utilities (api.ts, apiClient.ts, agentApi.ts, errorHandler.ts)
- `types/` - TypeScript type definitions

**State Management**:
- `AuthContext` - User authentication state
- `ProjectContext` - Active project and file state
- `Zustand` stores - Additional state management
- `TanStack Query` - Server state caching and synchronization

### Agent System

The AI Agent system is the core feature:

**Backend (apps/server/agent/)**:
- `service.py` - Main agent orchestration with streaming response
- `suggest_service.py` - AI-powered content suggestions
- `context/` - Context assembly and prioritization for RAG
- `tools/` - Agent tools (file_executor.py for file operations)
- `schemas/` - Request/response models
- `prompts/` - System prompts for different agent behaviors

**Frontend**:
- `useAgentStream.ts` - SSE (Server-Sent Events) streaming hook
- `ChatPanel.tsx` - Main AI chat interface
- `MessageList.tsx` - Message rendering with tool results
- `ToolResultCard.tsx` - Display tool execution results

### File Search

Global file search functionality for quickly finding files within the current project.

**Components**:
- `FileSearchInput` - Search input with debounce and IME support
- `SearchResultsDropdown` - Keyboard-navigable results dropdown
- `FileTypeFilter` - File type filtering dropdown

**Hook**: `useFileSearch`
- Client-side search with fuzzy matching
- 300ms debounce
- Max 50 results
- Case-insensitive

**Context**: `FileSearchContext`
- Global search state management
- Keyboard shortcut support

**Trigger**: Cmd+K (Mac) / Ctrl+K (Windows/Linux)

**Scope**: Current project files

**Matching**: Fuzzy, case-insensitive title search with relevance ranking (exact > prefix > contains)

**Features**:
- Real-time search with debouncing
- File type filtering (outline, draft, character, lore, material)
- Keyboard navigation (ArrowUp/Down, Enter, Escape)
- Global keyboard shortcut
- Mobile-responsive design
- i18n support (EN/ZH)
- IME composition support for Chinese input

## Key Configuration Files

### Backend Configuration

**Environment (.env)** - Only one LLM API key required:
```
# Pick one — all other settings have sensible defaults
DEEPSEEK_API_KEY=your-deepseek-api-key
# ANTHROPIC_API_KEY=sk-ant-xxx
```

Database defaults to SQLite (`./zenstory.db`). JWT secret auto-generated in development. See `apps/server/.env.example` for all options.

### Frontend Configuration

**Build Configuration** (`vite.config.ts`):
- Code splitting for optimal caching (react-vendor, ui-vendor, state-vendor, editor-vendor)
- Sitemap generation for SEO

**Linting** (`eslint.config.js`):
- TypeScript ESLint with React Hooks and React Refresh rules

## API Structure

All API routes are prefixed with `/api/v1/`:

**Authentication** (`api/auth.py`):
- `POST /register` - User registration
- `POST /login` - Login with email/password
- `POST /auth/google` - Google OAuth
- `POST /refresh` - Refresh access token

**Projects** (`api/projects.py`):
- `GET/POST /projects` - List/create projects
- `GET/PUT/DELETE /projects/{id}` - Project CRUD

**Files** (`api/files.py`):
- `GET/POST /projects/{id}/files` - List/create files
- `GET /projects/{id}/file-tree` - Get file tree structure
- `GET/PUT/DELETE /files/{id}` - File CRUD
- `POST /files/{id}/move` - Move file in tree

**Versions** (`api/versions.py`):
- `GET/POST /files/{id}/versions` - List/create versions
- `GET /files/{id}/versions/compare` - Compare two versions
- `POST /files/{id}/versions/{num}/rollback` - Rollback to version

**Agent** (`api/agent.py`):
- `POST /agent/chat` - AI chat with streaming (SSE)

**Chat** (`api/chat.py`):
- `GET/POST /projects/{id}/chats` - Chat session management
- `DELETE /chats/{id}` - Delete chat session

**Export** (`api/export.py`):
- `POST /projects/{id}/export` - Export project (docx, txt, md)

**Voice** (`api/voice.py`):
- `POST /voice/asr` - Speech-to-text (Tencent Cloud ASR)

## Important Implementation Notes

### File Model

The unified file model (`models/file_model.py`) supports multiple file types via `file_type` field:
- `outline` - Story/chapter outlines with hierarchical structure
- `draft` - Draft content with auto-save
- `character` - Character profiles with traits
- `lore` - World-building entries with categories

Files support parent-child relationships via `parent_id` for tree structure.

### Version History

Every file change creates a version snapshot (`services/file_version_service.py`):
- Automatic version creation on file update
- Diff comparison between versions
- One-click rollback to any version

### Agent Context System

The agent uses a sophisticated context assembly system (`agent/context/`):
- `assembler.py` - Collects relevant files/content
- `budget.py` - Manages token budget for context
- `prioritizer.py` - Prioritizes most relevant content

### Authentication Flow

1. JWT-based authentication with access + refresh tokens
2. Google OAuth support for social login
3. Protected routes use `Depends(get_current_user)` dependency
4. Frontend stores tokens in localStorage, auto-refreshes expired tokens

### Error Handling

**Backend**: Custom exception handler in `core/error_handler.py`:
- `APIException` - Base exception with status code
- Global handlers for HTTPException, ValidationError, and general exceptions
- Structured error responses with request ID for tracing

**Frontend**: `lib/errorHandler.ts` handles API errors:
- Token refresh on 401 errors
- User-friendly error messages
- Automatic retry logic

## Testing

No automated tests are currently implemented. When adding tests:
- Backend: pytest with TestClient from fastapi.testclient
- Frontend: React Testing Library + Vitest

## Deployment

**Production Architecture**:
- Frontend: Vercel (React + Vite)
- Backend: Railway (FastAPI + PostgreSQL)
- CDN: Cloudflare

See `README.md` for detailed deployment instructions including:
- Environment variable configuration
- Railway deployment steps
- Vercel deployment steps
- Cloudflare DNS/SSL setup

## Common Development Patterns

### Adding a New API Endpoint

1. Create route handler in appropriate `api/*.py` file
2. Keep logic minimal - delegate to `services/` layer
3. Use `Depends(get_session)` for database access
4. Add corresponding function to `apps/web/src/lib/api.ts`
5. Add TypeScript types to `apps/web/src/types/index.ts`

### Adding a New Component

1. Create in `apps/web/src/components/`
2. Use Tailwind CSS for styling (follow existing patterns)
3. Import from `lib/api.ts` for data fetching
4. Use TanStack Query mutations for writes
5. Handle loading/error states

### Database Schema Changes

1. Modify model in `apps/server/models/`
2. Create Alembic migration: `alembic revision --autogenerate -m "description"`
3. Apply migration: `alembic upgrade head`
4. Update TypeScript types in `apps/web/src/types/`

### Agent Tool Development

Tools are in `apps/server/agent/tools/`:
1. Create tool function with type hints
2. Register in `agent/service.py` tool registry
3. Update frontend `ToolResultCard.tsx` to display results