charlestehio/memefast
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a12fe359d968d4e0fdffb214a9b9c3e658907cde
memefast/CLAUDE.md
ct a12fe359d9 Update
2025-07-15 01:46:54 +08:00

12 KiB
Raw Blame History

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