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
- **Inertia.js** full-stack integration between Laravel and React
- **Zustand** for state management (VideoEditorStore, MediaStore, UserStore, PricingStore)
- **Radix UI** + **Tailwind CSS** for component library
- **Konva.js** + **React-Konva** for canvas-based video/meme editing
- **FFmpeg.wasm** for client-side media processing

#### 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/`

#### 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