# Environment Variables Configuration

This document provides a comprehensive guide to all environment variables required for the Prmbr - AI Prompt Studio application.

## 📋 Table of Contents

- [Database Configuration](#database-configuration)
- [Authentication (Supabase)](#authentication-supabase)
- [File Storage (Cloudflare R2)](#file-storage-cloudflare-r2)
- [Payment Processing (Stripe)](#payment-processing-stripe)
- [AI Model APIs](#ai-model-apis)
- [Application Settings](#application-settings)
- [Development vs Production](#development-vs-production)
- [Complete Configuration Examples](#complete-configuration-examples)

## 🗄️ Database Configuration

### Required Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string via Supabase/Prisma | `postgresql://username:password@localhost:5432/prmbr` |

### Development Setup
```bash
# Local PostgreSQL
DATABASE_URL="postgresql://username:password@localhost:5432/prmbr?schema=public"

# Supabase (Recommended)
DATABASE_URL="postgresql://postgres:[PASSWORD]@[PROJECT_REF].supabase.co:5432/postgres"

# Prisma Accelerate (For Cloudflare Workers)
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=your_api_key"
```

## 🔐 Authentication (Supabase)

### Required Variables

| Variable | Description | Where to Find |
|----------|-------------|---------------|
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL | Project Settings > API |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anonymous key | Project Settings > API |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key | Project Settings > API |

### Configuration
```bash
# Get these from your Supabase project dashboard
NEXT_PUBLIC_SUPABASE_URL="https://your-project-id.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
SUPABASE_SERVICE_ROLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Setup Instructions
1. Create a Supabase project at [supabase.com](https://supabase.com)
2. Go to Project Settings > API
3. Copy the Project URL and API keys
4. Enable Google OAuth in Authentication > Providers (optional)

## 📁 File Storage (Cloudflare R2)

### Required Variables

| Variable | Description | Where to Find |
|----------|-------------|---------------|
| `R2_ACCESS_KEY_ID` | R2 access key ID | R2 > Manage R2 API tokens |
| `R2_SECRET_ACCESS_KEY` | R2 secret access key | R2 > Manage R2 API tokens |
| `R2_ENDPOINT` | R2 S3-compatible endpoint | R2 > Settings |
| `R2_BUCKET_NAME` | R2 bucket name | R2 > Buckets |

### Configuration
```bash
# Cloudflare R2 Configuration
R2_ACCESS_KEY_ID="f1234567890abcdef1234567890abcde"
R2_SECRET_ACCESS_KEY="abc123def456ghi789jkl012mno345pqr678stu901"
R2_ENDPOINT="https://1234567890abcdef.r2.cloudflarestorage.com"
R2_BUCKET_NAME="prmbr-storage"
```

### Setup Instructions
1. Go to Cloudflare Dashboard > R2 Object Storage
2. Create a new R2 bucket
3. Generate R2 API tokens with read/write permissions
4. Note the endpoint URL from bucket settings

## 💳 Payment Processing (Stripe)

### Required Variables

| Variable | Description | Where to Find |
|----------|-------------|---------------|
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key | Stripe Dashboard > API keys |
| `STRIPE_SECRET_KEY` | Stripe secret key | Stripe Dashboard > API keys |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook endpoint secret | Stripe Dashboard > Webhooks |
| `NEXT_PUBLIC_STRIPE_PRO_PRICE_ID` | Stripe price ID for Pro plan | Stripe Dashboard > Products |

### Configuration
```bash
# Stripe Configuration
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_51234567890abcdefghijklmnopqrstuvwxyz"
STRIPE_SECRET_KEY="sk_live_51234567890abcdefghijklmnopqrstuvwxyz"
STRIPE_WEBHOOK_SECRET="whsec_1234567890abcdefghijklmnopqrstuvwxyz"
NEXT_PUBLIC_STRIPE_PRO_PRICE_ID="price_1234567890abcdefghijk"
```

### Setup Instructions
1. Create a Stripe account at [stripe.com](https://stripe.com)
2. Go to Dashboard > API keys and copy the keys
3. Create a webhook endpoint pointing to `/api/webhooks/stripe`
4. Create products and pricing plans in Stripe Dashboard
5. Copy the price ID for your Pro subscription plan

### Webhook Events to Listen
Configure your Stripe webhook to listen for these events:
- `checkout.session.completed`
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`
- `invoice.payment_failed`

## 🤖 AI Model APIs

### OpenRouter (Text Models)

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `OPENROUTER_API_KEY` | OpenRouter API key | [openrouter.ai](https://openrouter.ai) |

```bash
OPENROUTER_API_KEY="sk-or-v1-1234567890abcdefghijklmnopqrstuvwxyz"
```

### Replicate (Image/Video/Audio Models)

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `REPLICATE_API_TOKEN` | Replicate API token | [replicate.com](https://replicate.com) |

```bash
REPLICATE_API_TOKEN="r8_1234567890abcdefghijklmnopqrstuvwxyz"
```

### UniAPI (Multi-modal Models)

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `UNIAPI_API_KEY` | UniAPI API key | [uniapi.ai](https://uniapi.ai) |

```bash
UNIAPI_API_KEY="uniapi-1234567890abcdefghijklmnopqrstuvwxyz"
```

### Fal.ai (AI Generation Models)

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `FAL_API_KEY` | Fal.ai API key | [fal.ai](https://fal.ai) |

```bash
FAL_API_KEY="fal-1234567890abcdefghijklmnopqrstuvwxyz"
```

### API Key Setup Instructions

#### OpenRouter
1. Visit [openrouter.ai](https://openrouter.ai)
2. Sign up and go to API Keys
3. Create a new API key with appropriate credits

#### Replicate
1. Visit [replicate.com](https://replicate.com)
2. Sign up and go to Account > API tokens
3. Create a new token

#### UniAPI
1. Visit [uniapi.ai](https://uniapi.ai)
2. Sign up and get your API key from the dashboard
3. Add credits to your account

#### Fal.ai
1. Visit [fal.ai](https://fal.ai)
2. Sign up and get your API key from the dashboard
3. Add credits to your account

## ⚙️ Application Settings

### Required Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `NEXT_PUBLIC_APP_URL` | Application URL | `https://prmbr.com` |
| `NEXTAUTH_URL` | NextAuth URL (same as app URL) | `https://prmbr.com` |
| `NEXTAUTH_SECRET` | NextAuth secret for JWT signing | Random 32-character string |

### Optional Variables

| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `FEE_CALCULATION_MULTIPLIER` | Fee calculation multiplier for AI model costs | `10.0` | `5.0` |

### Configuration
```bash
# Application Settings
NEXT_PUBLIC_APP_URL="https://prmbr.com"
NEXTAUTH_URL="https://prmbr.com"
NEXTAUTH_SECRET="your-super-secret-nextauth-secret-32chars"

# Fee Calculation (Optional - defaults to 10x)
FEE_CALCULATION_MULTIPLIER="10.0"
```

### Generating NEXTAUTH_SECRET
```bash
# Generate a random secret
openssl rand -base64 32
```

## 🔄 Development vs Production

### Development Environment (.env.local)
```bash
# Use test/development keys
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXTAUTH_URL="http://localhost:3000"
```

### Production Environment
```bash
# Use live/production keys
STRIPE_SECRET_KEY="sk_live_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_..."
NEXT_PUBLIC_APP_URL="https://prmbr.com"
NEXTAUTH_URL="https://prmbr.com"
```

## 📝 Complete Configuration Examples

### 🚀 Full Development Configuration

Create a `.env.local` file:

```bash
# ===========================================
# PRMBR - AI PROMPT STUDIO
# Development Environment Configuration
# ===========================================

# Database
DATABASE_URL="postgresql://postgres:your_password@db.your-project.supabase.co:5432/postgres"

# Supabase Authentication
NEXT_PUBLIC_SUPABASE_URL="https://your-project-id.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlvdXItcHJvamVjdC1pZCIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjc5MzE2MDAwLCJleHAiOjE5OTQ4OTIwMDB9.example"
SUPABASE_SERVICE_ROLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlvdXItcHJvamVjdC1pZCIsInJvbGUiOiJzZXJ2aWNlX3JvbGUiLCJpYXQiOjE2NzkzMTYwMDAsImV4cCI6MTk5NDg5MjAwMH0.example"

# Cloudflare R2 Storage
R2_ACCESS_KEY_ID="f1234567890abcdef1234567890abcde"
R2_SECRET_ACCESS_KEY="abc123def456ghi789jkl012mno345pqr678stu901"
R2_ENDPOINT="https://1234567890abcdef.r2.cloudflarestorage.com"
R2_BUCKET_NAME="prmbr-dev-storage"

# Stripe Payment (Test Keys)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_51ABC123def456ghi789jkl012mno345PQR678stu901vwx234YZA567bcd890EFG"
STRIPE_SECRET_KEY="sk_test_51ABC123def456ghi789jkl012mno345PQR678stu901vwx234YZA567bcd890EFG"
STRIPE_WEBHOOK_SECRET="whsec_1234567890abcdefghijklmnopqrstuvwxyz"
NEXT_PUBLIC_STRIPE_PRO_PRICE_ID="price_1ABC123def456ghi789jkl01"

# AI Model APIs
OPENROUTER_API_KEY="sk-or-v1-1234567890abcdefghijklmnopqrstuvwxyzABCDEF1234567890"
REPLICATE_API_TOKEN="r8_1234567890abcdefghijklmnopqrstuvwxyzABCDEF"
UNIAPI_API_KEY="uniapi-1234567890abcdefghijklmnopqrstuvwxyzABCDEF"
FAL_API_KEY="fal-1234567890abcdefghijklmnopqrstuvwxyzABCDEF"

# Application Settings
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="super-secret-nextauth-development-key-32-chars-long"

# Fee Calculation (Optional - defaults to 10x)
FEE_CALCULATION_MULTIPLIER="10.0"
```

### 🌐 Full Production Configuration

For production deployment (Vercel/Cloudflare):

```bash
# ===========================================
# PRMBR - AI PROMPT STUDIO
# Production Environment Configuration
# ===========================================

# Database
DATABASE_URL="postgresql://postgres:your_password@db.your-project.supabase.co:5432/postgres"

# Supabase Authentication
NEXT_PUBLIC_SUPABASE_URL="https://your-project-id.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlvdXItcHJvamVjdC1pZCIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjc5MzE2MDAwLCJleHAiOjE5OTQ4OTIwMDB9.production"
SUPABASE_SERVICE_ROLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlvdXItcHJvamVjdC1pZCIsInJvbGUiOiJzZXJ2aWNlX3JvbGUiLCJpYXQiOjE2NzkzMTYwMDAsImV4cCI6MTk5NDg5MjAwMH0.production"

# Cloudflare R2 Storage
R2_ACCESS_KEY_ID="f1234567890abcdef1234567890abcde"
R2_SECRET_ACCESS_KEY="abc123def456ghi789jkl012mno345pqr678stu901"
R2_ENDPOINT="https://1234567890abcdef.r2.cloudflarestorage.com"
R2_BUCKET_NAME="prmbr-production-storage"

# Stripe Payment (Live Keys)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_51ABC123def456ghi789jkl012mno345PQR678stu901vwx234YZA567bcd890EFG"
STRIPE_SECRET_KEY="sk_live_51ABC123def456ghi789jkl012mno345PQR678stu901vwx234YZA567bcd890EFG"
STRIPE_WEBHOOK_SECRET="whsec_production_1234567890abcdefghijklmnopqrstuvwxyz"
NEXT_PUBLIC_STRIPE_PRO_PRICE_ID="price_1ABC123def456ghi789jkl01"

# AI Model APIs
OPENROUTER_API_KEY="sk-or-v1-production-1234567890abcdefghijklmnopqrstuvwxyzABCDEF"
REPLICATE_API_TOKEN="r8_production_1234567890abcdefghijklmnopqrstuvwxyz"
UNIAPI_API_KEY="uniapi-production-1234567890abcdefghijklmnopqrstuvwxyz"
FAL_API_KEY="fal-production-1234567890abcdefghijklmnopqrstuvwxyz"

# Application Settings
NEXT_PUBLIC_APP_URL="https://prmbr.com"
NEXTAUTH_URL="https://prmbr.com"
NEXTAUTH_SECRET="super-secret-production-nextauth-key-32-chars-long-secure"

# Fee Calculation (Optional - defaults to 10x)
FEE_CALCULATION_MULTIPLIER="10.0"
```

## 🔒 Security Best Practices

### 1. Never commit secrets to version control
```bash
# Add to .gitignore
.env.local
.env.production
.env
```

### 2. Use different keys for development and production

### 3. Rotate API keys regularly

### 4. Use environment variable managers in production
- Vercel: Project Settings > Environment Variables
- Cloudflare Workers: wrangler secret put
- Docker: Use secrets or environment files

### 5. Validate environment variables on startup
The application includes validation that checks for required environment variables and fails fast if any are missing.

## 🚨 Troubleshooting

### Common Issues

1. **Database Connection Fails**
   - Check DATABASE_URL format
   - Verify database server is running
   - Check firewall settings

2. **Supabase Authentication Issues**
   - Verify SUPABASE_URL and keys are correct
   - Check if the keys match the project
   - Ensure RLS policies are configured

3. **Stripe Webhook Issues**
   - Verify webhook endpoint is accessible
   - Check webhook secret matches
   - Ensure events are configured correctly

4. **AI API Issues**
   - Verify API keys are valid and have credits
   - Check rate limits
   - Ensure correct API endpoints

### Environment Variable Validation

The application validates all required environment variables on startup. If any are missing, you'll see specific error messages in the console.

## 📞 Support

For configuration help:
- Email: qsongtianlun@gmail.com
- Check the [project documentation](../README.md)
- Review the [CLAUDE.md](../CLAUDE.md) for development guidance

---

**⚠️ Important**: Keep all API keys and secrets secure. Never share them publicly or commit them to version control.