refactor: Modernize environment management and backend architecture

.env.example

@@ -0,0 +1,38 @@
+# =============================================================================
+# No More Jockeys - Environment Configuration
+# =============================================================================
+# This is the main environment file for the entire project.
+# Copy this to .env and fill in your actual values.
+
+# -----------------------------------------------------------------------------
+# ANTHROPIC API CONFIGURATION
+# -----------------------------------------------------------------------------
+# Required for AI functionality
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# -----------------------------------------------------------------------------
+# HELICONE MONITORING
+# -----------------------------------------------------------------------------
+# REQUIRED in production for request monitoring
+# OPTIONAL in development (will use direct Anthropic API if not set)
+HELICONE_API_KEY=your_helicone_key_here
+
+# -----------------------------------------------------------------------------
+# API URL CONFIGURATION
+# -----------------------------------------------------------------------------
+# Frontend will auto-detect based on NODE_ENV, but you can override:
+# 
+# For local development (default behavior):
+# NEXT_PUBLIC_API_URL=http://localhost:8000
+#
+# To test frontend locally against production backend:
+# NEXT_PUBLIC_API_URL=https://backend-pu7w8cumu-set4.vercel.app
+#
+# For production deployment:
+# NEXT_PUBLIC_API_URL=https://your-production-backend.vercel.app
+
+# -----------------------------------------------------------------------------
+# DEVELOPMENT MODE CONFIGURATION
+# -----------------------------------------------------------------------------
+# Uncomment to set explicit development mode
+# NODE_ENV=development

.gitignore

@@ -1,16 +1,36 @@
+# Dependencies
 node_modules/
-.envrc
+venv/
+__pycache__/
+
+# Environment files
 .env
 .env.local
+.env*.local
+
+# Build outputs
 .next/
-.vercel
-__pycache__/
-venv/
-*.pyc
 dist/
 build/
+
+# Deployment
+.vercel
+
+# Logs
 *.log
+
+# OS files
 .DS_Store
+.envrc
+
+# Editor files
 *.swp
 *.swo
 *~
+
+# Python
+*.pyc
+
+# Temporary files
+backend.log
+frontend.log

README.md

@@ -7,8 +7,26 @@ Multi-LLM No More Jockeys game implementation with separate backend and frontend
 - **Backend**: FastAPI Python application (`/backend`)
 - **Frontend**: Next.js React application (`/frontend`)
 
+## Quick Start
+
+```bash
+cp .env.example .env
+# Add your ANTHROPIC_API_KEY to .env
+./dev-local.sh
+```
+
 ## Development
 
+### Development Modes
+
+```bash
+./dev-local.sh      # Frontend + Backend locally
+./dev-hybrid.sh     # Frontend local → Production backend  
+./dev-backend.sh    # Backend only
+```
+
+### Alternative Development Commands
+
 ```bash
 # Install dependencies and start both services
 npm run dev
@@ -18,6 +36,15 @@ npm run dev:backend  # Starts on http://localhost:8000
 npm run dev:frontend # Starts on http://localhost:3000
 ```
 
+### Environment
+
+Edit `.env`:
+```bash
+ANTHROPIC_API_KEY=your_api_key_here
+HELICONE_API_KEY=optional_monitoring_key  # Optional - adds observability
+# NEXT_PUBLIC_API_URL=optional_override
+```
+
 ## Deployment
 
 This project uses GitHub Actions to automatically deploy to Vercel when changes are pushed to the main branch.
@@ -58,15 +85,16 @@ This project uses GitHub Actions to automatically deploy to Vercel when changes
 
 For production deployments, set these in your Vercel project settings:
 
+**Backend**:
+- `ANTHROPIC_API_KEY`: Your Anthropic API key (required)
+- `HELICONE_API_KEY`: Your Helicone API key (required in production)
+
 **Frontend**:
 - `NEXT_PUBLIC_API_URL`: Your backend Vercel URL
 
-**Backend**:
-- `ANTHROPIC_API_KEY`: Your Anthropic API key (if using AI features)
-
 ## Game Rules
 
-No More Jockeys is a game where players take turns naming a person and a category that person has never been. The challenge is to avoid categories that have already been "banned" by previous players.
+No More Jockeys is a game where players take turns naming a person and a category that person belongs to. That category becomes banned. Don't name anyone from banned categories or you're eliminated.
 
 ## Tech Stack