diff options
| -rw-r--r-- | CLAUDE.md | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..8bd9863d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,168 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +OpenCut is a free, open-source video editor built with Next.js, focusing on privacy (no server processing), multi-track timeline editing, and real-time preview. The project is a monorepo using Turborepo with multiple apps including a web application, desktop app (Tauri), background remover tools, and transcription services. + +## Essential Commands + +**Development:** +```bash +# Root level development +bun dev # Start all apps in development mode +bun build # Build all apps +bun lint # Lint all code using Ultracite +bun format # Format all code using Ultracite + +# Web app specific (from apps/web/) +cd apps/web +bun run dev # Start Next.js development server with Turbopack +bun run build # Build for production +bun run lint # Run Biome linting +bun run lint:fix # Fix linting issues automatically +bun run format # Format code with Biome + +# Database operations (from apps/web/) +bun run db:generate # Generate Drizzle migrations +bun run db:migrate # Run migrations +bun run db:push:local # Push schema to local development database +bun run db:push:prod # Push schema to production database +``` + +**Testing:** +- No unified test commands are currently configured +- Individual apps may have their own test setups + +## Architecture & Key Components + +### State Management +The application uses **Zustand** for state management with separate stores for different concerns: +- **editor-store.ts**: Canvas presets, layout guides, app initialization +- **timeline-store.ts**: Timeline tracks, elements, playback state +- **media-store.ts**: Media files and asset management +- **playback-store.ts**: Video playback controls and timing +- **project-store.ts**: Project-level data and persistence +- **panel-store.ts**: UI panel visibility and layout +- **keybindings-store.ts**: Keyboard shortcut management +- **sounds-store.ts**: Audio effects and sound management +- **stickers-store.ts**: Sticker/graphics management + +### Storage System +**Multi-layer storage approach:** +- **IndexedDB**: Projects, saved sounds, and structured data +- **OPFS (Origin Private File System)**: Large media files for better performance +- **Storage Service** (`lib/storage/`): Abstraction layer managing both storage types + +### Editor Architecture +**Core editor components:** +- **Timeline Canvas**: Custom canvas-based timeline with tracks and elements +- **Preview Panel**: Real-time video preview (currently DOM-based, planned binary refactor) +- **Media Panel**: Asset management with drag-and-drop support +- **Properties Panel**: Context-sensitive element properties + +### Media Processing +- **FFmpeg Integration**: Client-side video processing using @ffmpeg/ffmpeg +- **Background Removal**: Python-based tools with multiple AI models (U2Net, SAM, Gemini) +- **Transcription**: Separate service for audio-to-text conversion + +## Development Focus Areas + +**✅ Recommended contribution areas:** +- Timeline functionality and UI improvements +- Project management features +- Performance optimizations +- Bug fixes in existing functionality +- UI/UX improvements outside preview panel +- Documentation and testing + +**⚠️ Areas to avoid (pending refactor):** +- Preview panel enhancements (fonts, stickers, effects) +- Export functionality improvements +- Preview rendering optimizations + +**Reason:** The preview system is planned for a major refactor from DOM-based rendering to binary rendering for consistency with export and better performance. + +## Code Quality Standards + +**Linting & Formatting:** +- Uses **Biome** for JavaScript/TypeScript linting and formatting +- Extends **Ultracite** configuration for strict type safety and AI-friendly code +- Comprehensive accessibility (a11y) rules enforced +- Zero configuration approach with subsecond performance + +**Key coding standards from Ultracite:** +- Strict TypeScript with no `any` types +- No React imports (uses automatic JSX runtime) +- Comprehensive accessibility requirements +- Use `for...of` instead of `Array.forEach` +- No TypeScript enums, use const objects +- Always include error handling with try-catch + +## Environment Setup + +**Required environment variables (apps/web/.env.local):** +```bash +# Database +DATABASE_URL="postgresql://opencut:opencutthegoat@localhost:5432/opencut" + +# Authentication +BETTER_AUTH_SECRET="your-generated-secret-here" +BETTER_AUTH_URL="http://localhost:3000" + +# Redis +UPSTASH_REDIS_REST_URL="http://localhost:8079" +UPSTASH_REDIS_REST_TOKEN="example_token" + +# Content Management +MARBLE_WORKSPACE_KEY="workspace-key" +NEXT_PUBLIC_MARBLE_API_URL="https://api.marblecms.com" +``` + +**Docker services:** +```bash +# Start local database and Redis +docker-compose up -d +``` + +## Project Structure + +**Monorepo layout:** +- `apps/web/` - Main Next.js application +- `apps/desktop/` - Tauri desktop application +- `apps/bg-remover/` - Python background removal tools +- `apps/transcription/` - Audio transcription service +- `packages/` - Shared packages (auth, database) + +**Web app structure:** +- `src/components/` - React components organized by feature +- `src/stores/` - Zustand state management +- `src/hooks/` - Custom React hooks +- `src/lib/` - Utility functions and services +- `src/types/` - TypeScript type definitions +- `src/app/` - Next.js app router pages and API routes + +## Common Patterns + +**Error handling:** +```typescript +try { + const result = await processData(); + return { success: true, data: result }; +} catch (error) { + console.error('Operation failed:', error); + return { success: false, error: error.message }; +} +``` + +**Store usage:** +```typescript +const { tracks, addTrack, updateTrack } = useTimelineStore(); +``` + +**Media processing:** +```typescript +import { processVideo } from '@/lib/ffmpeg-utils'; +const processedVideo = await processVideo(inputFile, options); +```
\ No newline at end of file |