memefast/CLAUDE.md

# CLAUDE.md

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

## Development Commands

### Frontend Development
- `npm run dev` - Start Vite development server
- `npm run build` - Build for production
- `npm run build:ssr` - Build with SSR support
- `npm run lint` - Run ESLint with auto-fix
- `npm run types` - Run TypeScript type checking
- `npm run format` - Format code with Prettier
- `npm run format:check` - Check code formatting

### Backend Development
- `composer dev` - Start full development environment (Laravel server, queue worker, logs, Vite)
- `composer dev:ssr` - Start development with SSR
- `composer test` - Run PHP tests with Pest
- `php artisan serve` - Start Laravel development server
- `php artisan queue:listen --tries=1` - Start queue worker
- `php artisan pail --timeout=0` - Start log viewer

## Architecture Overview

### Stack
- **Backend**: Laravel 12 with PHP 8.2+
- **Frontend**: React 19 + TypeScript with Inertia.js
- **Database**: PostgreSQL with pgvector extension for embeddings
- **Queue System**: Laravel Horizon for job processing
- **Payment**: Laravel Cashier with Stripe integration
- **Media Processing**: FFmpeg integration via pbmedia/laravel-ffmpeg
- **Authentication**: Laravel Sanctum + Google OAuth via Socialite

### Core Application Structure

**MemeAI Generator Platform**: This is a meme generation platform that uses AI to create memes from user inputs.

#### Key Models & Relationships
- `User` - Uses Billable trait for Stripe, has UUID-based public IDs
- `Meme` - Generated memes with keyword categorization (action/emotion/misc)
- `MemeMedia` - Template media files for meme generation
- `BackgroundMedia` - Background images/videos for memes
- `Category` - Hierarchical categories using kalnoy/nestedset
- `UserUsage` & `UserPlan` - Usage tracking and subscription management
- `KeywordEmbedding` & `MemeMediaEmbedding` - Vector embeddings for content matching

#### AI Integration Points
- `CloudflareAI`, `OpenAI`, `RunwareAI` - Multiple AI service integrations
- `MemeGenerator` - Core meme generation logic with keyword matching via vector similarity
- Uses pgvector for semantic search and content matching

#### Frontend Architecture

**Core Stack & Integration**
- **React 19 + TypeScript** with Inertia.js for seamless full-stack Laravel integration
- **Vite** as build tool with HMR and optimized bundling
- **Error Boundaries** with detailed fallback components for robust error handling
- **Context Providers**: GA4, Mitt.js, and Axios contexts wrapped at app level

**State Management & Data Flow**
- **Zustand** with devtools for reactive state management
- **MediaStore**: AI generation, meme/background selection, API calls, generation history, job polling
- **VideoEditorStore**: Video playback state, text element selection for canvas interactions
- **UserStore**: Authentication, billing, credits, premium export functionality
- **PricingStore**: Subscription management and pricing tiers
- **localSettingsStore**: User preferences, UI settings, and appearance themes

**Component Communication Architecture**
- **Mitt.js Event System**: Decoupled event-driven communication between components
- **Core Events**: `video-play`, `video-reset`, `video-open-download-modal`, `open-ai-editor-sheet`, `text-element-selected`
- **Responsive Design**: Mobile-first approach with progressive enhancement and viewport detection hooks
- **Layout Calculations**: Dynamic responsive width calculations with ResizeObserver and MutationObserver

**Editor System Architecture**
- **Main Editor** (`editor.jsx`): Central orchestrator with responsive design, sidebar management, and viewport detection
- **Video Editor** (`video-editor.jsx`): Konva.js canvas with timeline processing, drag-and-drop, and FFmpeg export
- **Editor Controls** (`editor-controls.jsx`): Play/pause, reset, refresh, download controls via event emission
- **AI Integration** (`editor-ai-sheet.jsx`): AI generation interface with job polling and status tracking
- **Multiple Sidebars**: EditNavSidebar (content navigation), EditSidebar (main editing), TextSidebar (text customization)

**Media Processing & Canvas**
- **Konva.js + React-Konva** for high-performance canvas-based video editing
- **Timeline Support**: Video element positioning, text overlay management
- **FFmpeg.wasm** for client-side video processing and multi-format export
- **9:16 Aspect Ratio**: Optimized for social media with responsive scaling (720x1280px base)
- **Drag-and-Drop Interface**: Interactive element positioning with real-time preview

#### Media Processing Pipeline
- Video templates stored as JSON configurations
- Canvas-based editor with timeline support
- Server-side FFmpeg processing for final video generation
- S3/R2 storage integration via Laravel Filesystem

#### Key Helper Classes
- `MediaEngine` - Media processing utilities
- `PurchaseHelper`, `SubscriptionHelper` - Payment processing
- `WatermarkUsageHelper` - Usage tracking and limits
- `StripeHelper` - Stripe integration utilities

### Development Notes

#### Testing
- Uses Pest PHP for backend testing
- Test files in `tests/Feature/` and `tests/Unit/`
- Run tests with `composer test`

#### Code Organization
- Custom helpers in `app/Helpers/FirstParty/`
- Global helper functions in `app/Helpers/Global/helpers.php`
- Frontend components organized by feature in `resources/js/modules/`
- Reusable UI components in `resources/js/components/ui/` (Radix UI + Tailwind)
- State management stores in `resources/js/stores/`
- React hooks in `resources/js/hooks/`
- Custom plugins and context providers in `resources/js/plugins/`

#### Special Configurations
- CORS headers configured for FFmpeg.wasm in Vite config
- Vector search capabilities via PostgreSQL pgvector extension
- Hashids for public ID generation (users, etc.)
- Queue-based background processing for media generation

#### Environment-Specific Features
- Test routes can be enabled via `ENABLE_TEST_ROUTES=true`
- Uses Laravel Horizon for queue management in production
- Supports both regular and SSR deployments

## Platform Features Overview

### Core AI Features
- **Text-to-Meme Generation**: Users input text prompts, AI generates appropriate memes using vector similarity matching
- **Multi-AI Integration**: OpenAI, Cloudflare AI, and Runware AI for different generation tasks
- **Smart Keyword Matching**: PostgreSQL pgvector for semantic search and content matching
- **AI Hint System**: Provides keyword suggestions organized by action/emotion/misc categories
- **AI Caption & Background Generation**: Automatic witty captions and custom background creation

### Video/Media Editing
- **Canvas-Based Editor**: 9:16 aspect ratio video canvas (720x1280px) with responsive scaling
- **Drag-and-Drop Interface**: Interactive positioning of elements with timeline controls
- **Template Library**: 30+ meme video templates and 30+ AI-generated background media
- **Export System**: Multiple formats (MOV, WebM, GIF, WebP) with watermark-free premium exports
- **FFmpeg Integration**: Client-side processing via FFmpeg.wasm

### User Management & Authentication
- **Google OAuth + Email/Password**: Dual authentication methods via Laravel Sanctum
- **UUID-based Public IDs**: Secure user identification using Hashids
- **User Dashboard**: Personalized interface with usage statistics and generation history

### Credit System & Monetization
- **Credit-Based Economy**: 2 credits per meme generation (1 caption + 1 background)
- **Stripe Integration**: Laravel Cashier for subscriptions and one-time purchases
- **Usage Tracking**: Real-time credit balance, transaction history, and consumption analytics
- **Subscription Management**: Multiple plan types with billing portal access

### Technical Features
- **Queue Processing**: Laravel Horizon with background job processing and real-time status updates
- **Vector Search**: Semantic content matching using PostgreSQL pgvector extension
- **Responsive Design**: Mobile-first interface with progressive enhancement
- **Generation History**: Users can view last 20 generations with regeneration capability
- **Security**: CSRF protection, rate limiting, input validation, secure file handling

### Admin/Management
- **Content Management**: Categorized meme library with hierarchical categories (kalnoy/nestedset)
- **Background Generation Tool**: Admin interface for creating new background media
- **Usage Analytics**: Platform-wide statistics and user consumption patterns
- **Bulk Operations**: Mass content management and moderation tools

## Frontend Component Structure

### Editor System (`/resources/js/modules/editor/`)
- **Main Editor** (`editor.jsx`): Central responsive component managing canvas, sidebars, and responsive design
- **Editor Controls** (`editor-controls.jsx`): Video playback controls with play/pause, reset, refresh, and download
- **Editor Canvas** (`editor-canvas.jsx`): Konva.js-based canvas with drag-and-drop timeline editing
- **Multiple Sidebars**: EditNavSidebar, EditSidebar, TextSidebar for different editing modes
- **AI Integration** (`editor-ai-sheet.jsx`): AI-powered meme generation interface

### State Management Architecture
- **VideoEditorStore**: Video playback state, text element selection
- **MediaStore**: Meme/background selection, AI integration, API calls, generation history
- **UserStore**: User authentication and profile management
- **PricingStore**: Subscription and credit management
- **localSettingsStore**: User preferences and UI settings

### Component Communication
- **Mitt.js Event System**: Event-driven architecture for editor interactions
- **Common Events**: `video-play`, `video-reset`, `video-open-download-modal`, `open-ai-editor-sheet`, `text-element-selected`
- **Responsive Design**: Mobile-first with progressive enhancement, viewport detection hooks

### UI Component Library
- **Radix UI Base**: Comprehensive accessible component primitives
- **Custom Components**: Animated elements, error boundaries, tailwind breakpoint utilities
- **Styling**: Tailwind CSS with custom design system and responsive utilities

## Backend Architecture

### API Structure (`/routes/api.php`)
- **Authentication**: `/user/register`, `/user/login` (Sanctum-based)
- **User Management**: `/user/` (profile), `/user/subscribe`, `/user/purchase`, `/user/billing-portal`
- **Meme Generation**: `/user/generate_meme/*` (generate, status, active job, history)
- **Export System**: `/user/premium-export/*` (request, complete)
- **Media APIs**: `/app/init`, `/app/memes`, `/app/background`
- **AI Integration**: `/ai-hints` for keyword suggestions

### Controller Organization
- **FrontMediaController**: Media initialization and content delivery
- **UserAIController**: AI-powered meme generation with job processing
- **UserAccountController**: User profile and account management
- **UserPurchaseController**: Stripe integration and subscription management
- **UserExportController**: Premium export functionality
- **AdminControllers**: Background generation and admin dashboard

### Database Models & Relationships
- **User**: Billable trait for Stripe, UUID-based public IDs, soft deletes
- **Meme**: Generated memes with keyword categorization, relationships to media
- **MemeMedia**: Template media with pgvector embeddings for semantic search
- **BackgroundMedia**: Background assets with completion status
- **UserMemeGeneration**: Job tracking for async meme generation
- **UserUsage & UserPlan**: Credit tracking and subscription management
- **Category**: Hierarchical keyword organization (kalnoy/nestedset)

### Key Features
- **Queue-Based Processing**: GenerateMemeJob for async AI generation
- **Cache-Based Job Status**: Redis caching for real-time job status updates
- **Vector Search**: pgvector for semantic content matching
- **Credit System**: CreditsService for usage tracking and payment integration
- **Stripe Integration**: Laravel Cashier for subscriptions and payments
- **Media Processing**: FFmpeg integration for video generation
- **Authentication**: Laravel Sanctum + Google OAuth via Socialite