diff --git a/CLAUDE.md b/CLAUDE.md
index 15ca558..4c69319 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,11 +51,40 @@ #### AI Integration Points
 - 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
+
+**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
@@ -80,7 +109,10 @@ #### 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/`
+- 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
@@ -131,4 +163,66 @@ ### 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
\ No newline at end of file
+- **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
\ No newline at end of file