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