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

### Application Entry & Shell (`/resources/js/`)
- **app.tsx**: Main Inertia.js application entry with error boundaries, context providers (GA4, Mitt, Axios), and global toaster
- **app-shell.tsx**: Layout wrapper providing either header or sidebar variants using SidebarProvider
- **ssr.tsx**: Server-side rendering entry point for enhanced performance

### Editor System (`/resources/js/modules/editor/`)
- **editor.jsx**: Central responsive orchestrator managing canvas, sidebars, viewport detection, and responsive design
- **editor-controls.jsx**: Video playback controls with play/pause, reset, refresh, download via event emission
- **editor-canvas.jsx**: Responsive canvas wrapper that scales the video editor to fit different screen sizes
- **editor-ai-sheet.jsx**: AI-powered meme generation interface with job polling, status tracking, and credit management
- **editor-header.jsx**: Header component for the editor interface with navigation controls

### Canvas & Video Processing (`/resources/js/modules/editor/partials/canvas/`)
- **video-editor.jsx**: Core Konva.js canvas with timeline processing, video/image handling, and FFmpeg export
- **video-preview.jsx**: Video preview component with element selection and transformation utilities
- **video-download-modal.jsx**: Download interface for multiple export formats (MOV, WebM, GIF, WebP)
- **video-export.jsx**: Export functionality with FFmpeg.wasm integration and format conversion

### Sidebar Components (`/resources/js/modules/editor/partials/`)
- **edit-nav-sidebar.jsx**: Navigation sidebar for switching between memes and backgrounds
- **edit-sidebar.jsx**: Main editing sidebar with content selection interfaces
- **text-sidebar.jsx**: Text editing sidebar for customizing meme captions and text properties

### Authentication System (`/resources/js/modules/auth/`)
- **AuthDialog.jsx**: Modal dialog for Google OAuth authentication with login/signup switching
- **auth-user.jsx**: User authentication component and user state management

### State Management Stores (`/resources/js/stores/`)
- **MediaStore.js**: Comprehensive store for meme/background selection, AI generation, API calls, generation history, job polling
- **VideoEditorStore.js**: Video playback state, text element selection for canvas interactions
- **UserStore.js**: User authentication, billing, credits, premium export functionality
- **PricingStore.js**: Subscription management, pricing tiers, and upgrade flows
- **localSettingsStore.js**: User preferences, UI settings, appearance themes

### Page Components (`/resources/js/pages/`)
- **Home System**: `home.tsx` with Hero, Features, FAQ sections and animated counters
- **Dashboard**: `dashboard.tsx` with user analytics and generation history
- **Authentication Pages**: Login, register, password reset, email verification flows
- **Settings Pages**: Profile, appearance, password management interfaces
- **Admin Pages**: Dashboard, background generation tools for content management

### UI Component Library (`/resources/js/components/ui/`)
- **Radix UI Base**: Complete accessible component primitives (buttons, dialogs, sheets, forms, tables)
- **Form Controls**: Input, textarea, select, checkbox, radio-group with validation
- **Layout Components**: Card, dialog, sheet, sidebar, tabs, accordion for structured layouts
- **Feedback Components**: Alert, toast, progress, skeleton, spinner for user feedback
- **Navigation**: Breadcrumb, navigation-menu, pagination for app navigation
- **Data Display**: Table, avatar, badge, chart for content presentation

### Enhanced UI Components (`/resources/js/components/magicui/` & `/resources/js/components/reactbits/`)
- **Animation Components**: Animated beam, gradient text, sparkles text, word rotation
- **Special Effects**: CountUp, GlitchText, ShinyText, TiltedCard for engaging interactions
- **Layout Enhancements**: Bento grid, marquee, pulsating button for dynamic layouts

### Utility Systems (`/resources/js/`)
- **Hooks**: Custom React hooks for appearance, mobile detection, user initials, navigation
- **Plugins**: Context providers for Axios, Google Analytics, Mitt.js event system
- **Layouts**: Flexible layout system with auth, app, and settings variants
- **Types**: TypeScript definitions for global types, API responses, and component props

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