docs: Update README with comprehensive Portkey setup and configuration

README.md

@@ -6,29 +6,32 @@
 
 ## Overview
 
-Chaos Coder is a Next.js application that generates five variations of web applications simultaneously using AI. This tool helps developers quickly explore different implementation possibilities for their web application ideas.
+Chaos Coder is a Next.js application that generates multiple variations of web applications simultaneously using AI. This tool helps developers quickly explore different implementation possibilities for their web application ideas with intelligent fallback across multiple AI providers.
 
 **Note:** All the code for this project is located in the `nextjs-web-app` folder.
 
 ## Purpose
 
-The purpose of Chaos Coder is to accelerate the development process by providing multiple variations of code solutions for web applications. By generating five different approaches at once, developers can compare and choose the best implementation for their specific needs.
+The purpose of Chaos Coder is to accelerate the development process by providing multiple variations of code solutions for web applications. By generating different approaches simultaneously, developers can compare and choose the best implementation for their specific needs.
 
 ## Features
 
-- Generates five unique web application variations
-- Real-time code preview for each variation
-- Interactive interface with theme toggling
-- Voice input support for hands-free prompting
-- Keyboard shortcuts for quick access to tools
+- **Multi-Provider AI Generation**: Uses Portkey AI Gateway with intelligent fallbacks across Cerebras, Groq, OpenRouter, and OpenAI
+- **Multiple Framework Support**: Generate apps using Tailwind CSS, Bootstrap, Materialize, PatternFly, or Pure CSS
+- **Real-time Code Preview**: Live preview of generated applications in iframe
+- **User Authentication**: Secure user accounts with Supabase Auth
+- **Responsive Design**: Works seamlessly on desktop and mobile devices
+- **Theme Toggle**: Dark/light mode support
+- **Code Export**: Copy and download generated code
+- **Fullscreen Preview**: Dedicated fullscreen mode for testing applications
 
 ## Tech Stack
 
-- Next.js 14
-- TypeScript
-- Tailwind CSS
-- Framer Motion
-- Hugging Face Inference API
+- **Frontend**: Next.js 15, TypeScript, Tailwind CSS 4, Framer Motion
+- **AI Gateway**: Portkey AI with multi-provider fallbacks
+- **Authentication**: Supabase Auth with SSR
+- **Deployment**: Vercel-ready configuration
+- **Styling**: Tailwind CSS with custom design system
 
 ## Setup
 
@@ -45,60 +48,194 @@ cd chaos-coder/nextjs-web-app
 npm install
 ```
 
-### 3. Set up environment variables
+### 3. Set up Portkey AI Gateway
 
-Create a `.env.local` file in the project root:
+Portkey serves as our AI gateway, providing intelligent fallbacks across multiple AI providers.
+
+1. **Create a Portkey account** at [portkey.ai](https://portkey.ai)
+2. **Get your Portkey API key** from the dashboard
+3. **Set up Virtual Keys** for AI providers:
+   - Go to the "Virtual Keys" section in your Portkey dashboard
+   - Add virtual keys for the providers you want to use:
+     - **Cerebras** (recommended for speed)
+     - **Groq** (fast inference)
+     - **OpenRouter** (wide model selection)
+     - **OpenAI** (reliable fallback)
+   - Note down the virtual key IDs for each provider
+
+### 4. Set up Supabase (Optional - for authentication)
+
+If you want user authentication features:
+
+1. **Create a Supabase project** at [supabase.com](https://supabase.com)
+2. **Get your project credentials** from Settings > API
+3. **Enable authentication providers** you want to support
+
+### 5. Configure environment variables
+
+Copy the example environment file and configure your settings:
+
+```bash
+cp .env.example .env.local
+```
+
+Then edit `.env.local` with your actual values:
 
 ```bash
-HF_API_TOKEN=your_huggingface_api_token
+# Required - Get from https://portkey.ai
+PORTKEY_API_KEY=your_portkey_api_key_here
+
+# Optional - For authentication features
+NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
+
+# Optional - Use your own virtual keys (uncomment to override defaults)
+# PORTKEY_CEREBRAS_VIRTUAL_KEY=your_cerebras_virtual_key
+# PORTKEY_GROQ_VIRTUAL_KEY=your_groq_virtual_key
+# PORTKEY_OPENROUTER_VIRTUAL_KEY=your_openrouter_virtual_key
+# PORTKEY_OPENAI_VIRTUAL_KEY=your_openai_virtual_key
 ```
 
-### 4. Run the development server
+### 6. Run the development server
 
 ```bash
 npm run dev
 ```
 
+Open [http://localhost:3000](http://localhost:3000) to see the application.
+
 ## Usage
 
-1. Access the application in your web browser at http://localhost:3000
-2. Enter your web application requirements or ideas in the input form
-3. View and compare the five different application variations
-4. Use the code preview panel to inspect and edit the generated code
-5. Use keyboard shortcuts for quick access to tools:
-   - Shift+L: Open prompt input
-   - Shift+P: Open performance metrics
+### Basic Usage
+
+1. **Access the application** at http://localhost:3000
+2. **Enter your requirements** in the prompt textarea
+3. **Select number of variations** (1-5) to generate
+4. **Choose a CSS framework** (optional):
+   - Tailwind CSS (default)
+   - Bootstrap 5
+   - Materialize CSS
+   - PatternFly
+   - Pure CSS
+5. **Click "Generate Web Apps"** to create variations
+6. **Preview and interact** with generated applications
+7. **Use fullscreen mode** for better testing experience
+8. **Copy code** when you find a variation you like
+
+### Advanced Features
+
+- **Authentication**: Sign up/login to save your generations
+- **Theme Toggle**: Switch between light and dark modes
+- **Responsive Design**: Test on different screen sizes
+- **Framework Variations**: Each generation can use different CSS frameworks
+- **Intelligent Fallbacks**: If one AI provider fails, automatically tries the next
 
 ## Development
 
-To start the development server:
+### Development Commands
 
 ```bash
+# Start development server with Turbopack
 npm run dev
-```
-
-To build for production:
 
-```bash
+# Build for production
 npm run build
+
+# Start production server
+npm start
+
+# Run linting
+npm run lint
+
+# Deploy (if configured)
+npm run deploy
 ```
 
-To start the production server:
+### Project Structure
 
-```bash
-npm start
 ```
+nextjs-web-app/
+├── src/
+│   ├── app/
+│   │   ├── api/generate/          # AI generation API endpoint
+│   │   ├── results/               # Results page
+│   │   └── signup/                # Authentication pages
+│   ├── components/
+│   │   ├── ui/                    # Reusable UI components
+│   │   ├── AppTile.tsx            # Generated app preview
+│   │   ├── FullscreenPreview.tsx  # Fullscreen mode
+│   │   └── ThemeToggle.tsx        # Theme switching
+│   ├── context/
+│   │   └── ThemeContext.tsx       # Theme management
+│   └── lib/
+│       ├── supabase/              # Supabase client setup
+│       └── utils.ts               # Utility functions
+├── public/                        # Static assets
+└── package.json                   # Dependencies and scripts
+```
+
+## Configuration
+
+### Environment Variables
+
+All environment variables should be placed in `.env.local` in the `nextjs-web-app` directory:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORTKEY_API_KEY` | Yes | Your Portkey API key for AI gateway access |
+| `NEXT_PUBLIC_SUPABASE_URL` | No | Supabase project URL (for authentication) |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | No | Supabase anonymous key (for authentication) |
+| `PORTKEY_CEREBRAS_VIRTUAL_KEY` | No | Override default Cerebras virtual key |
+| `PORTKEY_GROQ_VIRTUAL_KEY` | No | Override default Groq virtual key |
+| `PORTKEY_OPENROUTER_VIRTUAL_KEY` | No | Override default OpenRouter virtual key |
+| `PORTKEY_OPENAI_VIRTUAL_KEY` | No | Override default OpenAI virtual key |
+
+### AI Provider Setup
+
+The application uses Portkey's virtual keys for AI provider management. The default configuration includes:
+
+- **Cerebras**: Fast inference with Qwen-3-32B model
+- **Groq**: High-speed inference with Llama-3.2-1B
+- **OpenRouter**: Access to Gemini Flash 1.5 8B
+- **OpenAI**: GPT-4o-mini as reliable fallback
 
-## Note
+To use your own providers, set the corresponding environment variables in `.env.local` (see configuration section above).
 
-For best results, be as specific as possible when describing your application requirements. The more detailed your input, the more tailored the generated solutions will be.
+### Deployment
+
+The application is configured for deployment on Vercel:
+
+1. **Connect your repository** to Vercel
+2. **Set environment variables** in Vercel dashboard
+3. **Deploy** - the build will automatically optimize for production
+
+For other platforms, ensure you:
+- Set all required environment variables
+- Configure the build command: `npm run build`
+- Set the start command: `npm start`
+
+## Tips for Best Results
+
+- **Be specific** in your prompts - detailed requirements lead to better generations
+- **Try different frameworks** - each CSS framework offers unique design patterns
+- **Use multiple variations** - compare different approaches to find the best solution
+- **Test responsiveness** - use fullscreen mode to test on different screen sizes
+- **Iterate** - use the update feature to refine generated applications
 
 ## Demo
 
 Check out the demo GIF at the top of this README to see Chaos Coder in action.
 
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines and feel free to submit issues and pull requests.
+
 ## Community
 
 Join our Discord community for support, discussions, and updates:
 
 [Join the Discord Server](https://discord.gg/cK9WeQ7jPq)
+
+## License
+
+This project is open source. See the LICENSE file for details.

nextjs-web-app/.env.example

@@ -0,0 +1,58 @@
+# Chaos Coder Environment Configuration
+# Copy this file to .env.local and fill in your actual values
+
+# =============================================================================
+# PORTKEY AI GATEWAY (REQUIRED)
+# =============================================================================
+# Get your API key from https://portkey.ai
+# This is required for AI generation functionality
+PORTKEY_API_KEY=your_portkey_api_key_here
+
+# =============================================================================
+# PORTKEY VIRTUAL KEYS (OPTIONAL)
+# =============================================================================
+# If you want to use your own virtual keys instead of the defaults
+# Create these in your Portkey dashboard under "Virtual Keys"
+# PORTKEY_CEREBRAS_VIRTUAL_KEY=your_cerebras_virtual_key
+# PORTKEY_GROQ_VIRTUAL_KEY=your_groq_virtual_key
+# PORTKEY_OPENROUTER_VIRTUAL_KEY=your_openrouter_virtual_key
+# PORTKEY_OPENAI_VIRTUAL_KEY=your_openai_virtual_key
+
+# =============================================================================
+# SUPABASE AUTHENTICATION (OPTIONAL)
+# =============================================================================
+# Only required if you want user authentication features
+# Get these from your Supabase project settings > API
+NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
+
+# =============================================================================
+# SETUP INSTRUCTIONS
+# =============================================================================
+# 
+# 1. PORTKEY SETUP (Required):
+#    - Sign up at https://portkey.ai
+#    - Get your API key from the dashboard
+#    - Optionally set up virtual keys for different AI providers:
+#      * Cerebras (fast inference)
+#      * Groq (high-speed processing)  
+#      * OpenRouter (wide model selection)
+#      * OpenAI (reliable fallback)
+#
+# 2. SUPABASE SETUP (Optional - for authentication):
+#    - Create a project at https://supabase.com
+#    - Go to Settings > API to get your credentials
+#    - Enable authentication providers you want to support
+#
+# 3. VIRTUAL KEYS (Optional):
+#    If you want to use your own virtual keys instead of defaults,
+#    uncomment and set the PORTKEY_*_VIRTUAL_KEY variables above
+#
+# =============================================================================
+# NOTES
+# =============================================================================
+# - Never commit .env.local to version control
+# - The app will work with just PORTKEY_API_KEY for basic functionality
+# - Supabase variables are only needed for user authentication features
+# - Virtual keys can be customized via environment variables (see above)
+# - Default virtual keys are provided but you can override them

nextjs-web-app/.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel

nextjs-web-app/src/app/api/generate/route.ts

@@ -31,7 +31,13 @@ export async function POST(req: NextRequest) {
       );
     }
 
-    // Configure Portkey with main provider (groq) and fallback (openrouter)
+    // Configure virtual keys - use environment variables if available, otherwise use defaults
+    const cerebrasVirtualKey = process.env.PORTKEY_CEREBRAS_VIRTUAL_KEY || "cerebras-b79172";
+    const groqVirtualKey = process.env.PORTKEY_GROQ_VIRTUAL_KEY || "groq-virtual-ke-9479cd";
+    const openrouterVirtualKey = process.env.PORTKEY_OPENROUTER_VIRTUAL_KEY || "openrouter-07e727";
+    const openaiVirtualKey = process.env.PORTKEY_OPENAI_VIRTUAL_KEY || "openai-9c929c";
+
+    // Configure Portkey with intelligent fallback across multiple AI providers
     const portkey = new Portkey({
       apiKey: portkeyApiKey,
       config: {
@@ -40,25 +46,25 @@ export async function POST(req: NextRequest) {
         },
         targets: [
           {
-            virtual_key: "cerebras-b79172",
+            virtual_key: cerebrasVirtualKey,
             override_params: {
               model: "qwen-3-32b",
             },
           },
           {
-            virtual_key: "groq-virtual-ke-9479cd",
+            virtual_key: groqVirtualKey,
             override_params: {
               model: "llama-3.2-1b-preview",
             },
           },
           {
-            virtual_key: "openrouter-07e727",
+            virtual_key: openrouterVirtualKey,
             override_params: {
               model: "google/gemini-flash-1.5-8b",
             },
           },
           {
-            virtual_key: "openai-9c929c",
+            virtual_key: openaiVirtualKey,
             override_params: {
               model: "gpt-4o-mini",
             },