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