# Chameleon AI SaaS Boilerplate - Complete Documentation ## Project Overview Chameleon is a comprehensive Next.js boilerplate specifically designed for building AI video SaaS startups. It provides a complete, production-ready foundation that allows developers to launch their AI-powered video generation businesses in hours, not weeks. ## Core Value Proposition - **Rapid Development**: Get from idea to MVP in hours - **AI-First Architecture**: Built specifically for AI video generation services - **Production Ready**: Includes authentication, payments, user management, and admin systems - **Multi-language Support**: Global-ready with 15 language support - **Scalable Architecture**: Built with modern best practices and scalable patterns ## Detailed Feature Set ### AI Video Generation - **Kling AI Integration**: High-quality video generation with multiple models - **Seedance Integration**: Alternative video generation provider - **Image Generation**: DALL-E, Replicate, and Kling image models - **Text Generation**: Multiple LLM providers (OpenAI, DeepSeek, OpenRouter, SiliconFlow) - **Text-to-Speech**: Voice synthesis capabilities - **Streaming Support**: Real-time AI response streaming ### User Management & Authentication - **NextAuth.js Integration**: Secure authentication system - **Google OAuth**: One-tap login with Google - **User Profiles**: Complete user profile management - **Session Management**: Secure session handling - **Role-based Access**: Admin and user role separation ### Payment & Subscription System - **Stripe Integration**: Complete payment processing - **Subscription Management**: Monthly and yearly plans - **Credit System**: Flexible credit-based pricing model - **Order Management**: Complete order tracking and management - **Webhook Handling**: Secure payment webhook processing ### Multi-language Support (15 Languages) - **English**: Primary language - **Chinese (Traditional)**: Full translation support - **Japanese**: Complete localization - **Korean**: Full translation - **French**: Complete localization - **Spanish**: Full translation - **German**: Complete localization - **Vietnamese**: Full translation - **Portuguese**: Complete localization - **Hindi**: Full translation - **Indonesian**: Complete localization - **Arabic**: Full translation - **Turkish**: Complete localization - **Thai**: Full translation - **Polish**: Complete localization ### Admin Dashboard - **User Management**: View, edit, and manage users - **Order Management**: Track and manage all orders - **AI Configuration**: Manage AI provider keys and settings - **Credit Rules**: Configure credit consumption rules - **Price Tier Management**: Manage pricing and credit tiers - **Credit Statistics**: Analytics and reporting - **User Feedback**: Manage user feedback and support - **Blog Management**: Content management system ### User Center - **AI Generator**: Main AI generation interface - **My Orders**: Order history and management - **My Credits**: Credit balance and history - **API Keys**: API key management for developers - **My Invites**: Referral system management ### Technical Architecture #### Frontend - **Next.js 15**: Latest version with App Router - **TypeScript**: Full type safety - **Tailwind CSS**: Utility-first CSS framework - **Shadcn UI**: Modern, accessible component library - **React 18**: Latest React features - **Responsive Design**: Mobile-first approach #### Backend - **API Routes**: Next.js API routes for backend logic - **Drizzle ORM**: Type-safe database operations - **PostgreSQL/MySQL**: Flexible database support - **Server Actions**: Modern server-side data mutations #### Database Schema - **Users**: User accounts and profiles - **Orders**: Payment and subscription data - **Credits**: Credit balance and transactions - **AI Provider Keys**: API key management - **Credit Rules**: Pricing and consumption rules - **Price Tier Credits**: Subscription tier configurations - **Generations**: AI generation history - **Feedback**: User feedback and support #### Internationalization - **next-intl**: Professional i18n solution - **Modular Structure**: Page-specific translations - **Dynamic Loading**: Efficient translation loading - **Locale Detection**: Automatic language detection - **SEO Optimized**: Language-specific URLs ### Development Features - **Hot Reload**: Fast development experience - **Type Safety**: Full TypeScript coverage - **ESLint & Prettier**: Code quality and formatting - **Git Hooks**: Pre-commit quality checks - **Environment Management**: Secure environment variable handling ### Deployment & DevOps - **Vercel Ready**: Optimized for Vercel deployment - **Environment Variables**: Secure configuration management - **Database Migrations**: Automated database setup - **Seed Data**: Initial data population - **Health Checks**: System monitoring endpoints ### Security Features - **Authentication**: Secure user authentication - **Authorization**: Role-based access control - **Data Validation**: Input validation and sanitization - **CSRF Protection**: Cross-site request forgery protection - **Rate Limiting**: API rate limiting - **Environment Security**: Secure environment variable handling ### Performance Optimizations - **Static Generation**: Pre-rendered pages for speed - **Image Optimization**: Next.js image optimization - **Code Splitting**: Automatic code splitting - **Caching**: Strategic caching implementation - **CDN Ready**: Content delivery network optimization ### Documentation System - **MDX Support**: Rich documentation with React components - **Search**: Documentation search functionality - **Navigation**: Hierarchical documentation structure - **Multi-language Docs**: Localized documentation - **API Documentation**: Complete API reference ### Business Features - **Analytics**: User behavior tracking - **Referral System**: User referral program - **Feedback System**: User feedback collection - **Blog System**: Content management - **SEO Optimization**: Search engine optimization - **Social Sharing**: Social media integration ## File Structure Details ### App Router Structure ``` src/app/ ├── [locale]/ # Internationalized routes │ ├── (default)/ # Public pages │ │ ├── page.tsx # Homepage │ │ ├── pricing/ # Pricing page │ │ ├── showcase/ # Showcase page │ │ ├── blog/ # Blog pages │ │ └── contact/ # Contact page │ ├── (console)/ # User center │ │ └── console/ # User dashboard │ └── (admin)/ # Admin system │ └── admin/ # Admin dashboard ├── api/ # API routes │ ├── auth/ # Authentication endpoints │ ├── ai/ # AI generation endpoints │ ├── stripe/ # Payment webhooks │ └── admin/ # Admin API endpoints └── (legal)/ # Legal pages ├── privacy-policy/ # Privacy policy └── terms-of-service/ # Terms of service ``` ### Component Architecture ``` src/components/ ├── blocks/ # Layout components │ ├── header/ # Site header │ ├── footer/ # Site footer │ └── hero/ # Hero sections ├── ui/ # Reusable UI components │ ├── button.tsx # Button component │ ├── input.tsx # Input component │ ├── card.tsx # Card component │ └── ... # Other UI components ├── console/ # User center components │ ├── sidebar/ # User navigation │ └── dashboard/ # Dashboard components ├── admin/ # Admin components │ ├── sidebar/ # Admin navigation │ └── dashboard/ # Admin dashboard └── docs/ # Documentation components ├── DocsLayout.tsx # Documentation layout ├── DocsSidebar.tsx # Documentation navigation └── DocsHeader.tsx # Documentation header ``` ### Internationalization Structure ``` src/i18n/ ├── messages/ # Common translations │ ├── en.json # English translations │ ├── zh.json # Chinese translations │ └── ja.json # Japanese translations ├── pages/ # Page-specific translations │ ├── landing/ # Landing page translations │ ├── console/ # User center translations │ ├── admin/ # Admin system translations │ ├── pricing/ # Pricing page translations │ └── showcase/ # Showcase page translations ├── locale.ts # Locale configuration ├── routing.ts # Routing configuration └── request.ts # Request configuration ``` ## API Endpoints ### Authentication - `POST /api/auth/signin` - User sign in - `POST /api/auth/signout` - User sign out - `GET /api/auth/session` - Get current session - `POST /api/auth/callback/google` - Google OAuth callback ### AI Generation - `POST /api/ai/generate/text` - Text generation - `POST /api/ai/generate/image` - Image generation - `POST /api/ai/generate/video` - Video generation - `POST /api/ai/generate/tts` - Text-to-speech ### User Management - `GET /api/user/profile` - Get user profile - `PUT /api/user/profile` - Update user profile - `GET /api/user/credits` - Get credit balance - `GET /api/user/orders` - Get order history ### Admin - `GET /api/admin/users` - Get all users - `PUT /api/admin/users/[id]` - Update user - `GET /api/admin/orders` - Get all orders - `GET /api/admin/analytics` - Get analytics data ### Payment - `POST /api/stripe/create-checkout` - Create checkout session - `POST /api/stripe/webhook` - Stripe webhook handler - `GET /api/stripe/portal` - Customer portal ## Environment Variables ### Required - `DATABASE_URL` - Database connection string - `NEXTAUTH_SECRET` - NextAuth.js secret - `NEXTAUTH_URL` - Application URL - `GOOGLE_CLIENT_ID` - Google OAuth client ID - `GOOGLE_CLIENT_SECRET` - Google OAuth client secret - `STRIPE_SECRET_KEY` - Stripe secret key - `STRIPE_PUBLISHABLE_KEY` - Stripe publishable key - `STRIPE_WEBHOOK_SECRET` - Stripe webhook secret ### AI Provider Keys - `OPENAI_API_KEY` - OpenAI API key - `DEEPSEEK_API_KEY` - DeepSeek API key - `KLING_API_KEY` - Kling AI API key - `SEEDANCE_API_KEY` - Seedance API key - `REPLICATE_API_TOKEN` - Replicate API token ### Optional - `NEXT_PUBLIC_APP_URL` - Public application URL - `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Public Stripe key - `NEXT_PUBLIC_GOOGLE_CLIENT_ID` - Public Google client ID ## Database Schema ### Users Table - `id` - Primary key - `email` - User email - `name` - User name - `image` - Profile image URL - `credits` - Credit balance - `created_at` - Account creation date - `updated_at` - Last update date ### Orders Table - `id` - Primary key - `user_id` - Foreign key to users - `stripe_order_id` - Stripe order ID - `amount` - Order amount - `status` - Order status - `created_at` - Order creation date ### Credits Table - `id` - Primary key - `user_id` - Foreign key to users - `amount` - Credit amount - `type` - Credit type (earned/spent) - `description` - Transaction description - `created_at` - Transaction date ### AI Provider Keys Table - `id` - Primary key - `provider_name` - AI provider name - `api_key` - Encrypted API key - `model_config` - JSON model configuration - `is_enabled` - Provider status - `created_at` - Creation date ## Deployment Guide ### Vercel Deployment 1. Connect GitHub repository to Vercel 2. Set environment variables in Vercel dashboard 3. Configure custom domain (optional) 4. Deploy automatically on push to main branch ### Database Setup 1. Create PostgreSQL database (Vercel Postgres recommended) 2. Set `DATABASE_URL` environment variable 3. Run database migrations: `pnpm db:push` 4. Seed initial data: `pnpm db:seed` ### Environment Configuration 1. Copy `.env.example` to `.env.local` 2. Fill in all required environment variables 3. Test configuration with `pnpm dev` ## Development Workflow ### Getting Started 1. Clone repository 2. Install dependencies: `pnpm install` 3. Set up environment variables 4. Run database setup 5. Start development server: `pnpm dev` ### Code Quality - TypeScript for type safety - ESLint for code linting - Prettier for code formatting - Husky for git hooks - Pre-commit checks for quality ### Testing - Unit tests for utilities - Integration tests for API routes - E2E tests for critical user flows - Performance testing for AI endpoints ## Version History ### v3.3.6 (Current) - Fixed locale preservation in docs navigation - Improved internationalization handling - Enhanced user experience ### v3.3.5 - Database seed data localization - Complete Japanese pricing translation - Brand resource updates ### v3.3.3 - Full Japanese language support - Internationalization structure refactor - Modular translation system ### v3.3.0 - Major internationalization update - 15 language support - Improved navigation system ## Support & Community - **Documentation**: Comprehensive docs at `/docs` - **GitHub**: Open source repository - **Issues**: Bug reports and feature requests - **Discussions**: Community discussions and Q&A ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request --- *Last updated: January 27, 2025* *Version: v3.3.6* *Maintainer: Chameleon Team*