# Environment Variables Configuration

## Required Environment Variables

### Clerk Authentication Configuration
```bash
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
```
**Description:** Clerk Publishable Key for frontend user authentication.

**How to get:**
1. Sign up at https://clerk.com/
2. Create a new application
3. Navigate to API Keys section
4. Copy the Publishable Key (starts with `pk_test_` or `pk_live_`)
5. Paste into .env file

**Usage:**
- User authentication (sign in, sign up)
- Session management
- User profile management
- Multi-factor authentication

**Backend Keys (Supabase Secrets):**
- `CLERK_SECRET_KEY`: Backend API operations (starts with `sk_test_` or `sk_live_`)
- `CLERK_WEBHOOK_SECRET`: Webhook signature verification (starts with `whsec_`)

**Documentation:** See [CLERK_SETUP_GUIDE.md](./CLERK_SETUP_GUIDE.md) for detailed setup instructions.

---

### OpenAI API Configuration
```bash
VITE_OPENAI_API_KEY=sk-...
```
**Description:** OpenAI API key for personalized route generation using GPT-4.

**How to get:**
1. Sign up at https://platform.openai.com/
2. Navigate to API Keys section
3. Create a new API key
4. Copy and paste into .env file

**Usage:**
- Personalized route generation based on user preferences
- Place descriptions and recommendations
- AI-powered itinerary optimization

**Rate Limits:**
- Client-side rate limiting: 10 requests per hour per user
- Server-side rate limiting: 20 AI suggestions per hour (via Edge Function)

---

### MapTiler API Configuration
```bash
VITE_MAPTILER_API_KEY=qkmdHs3dr0gUcmKEW3rK
VITE_MAPTILER_STYLE_URL=https://api.maptiler.com/maps/019c7033-5c53-7c2d-916e-711c182440f0/style.json
```
**Description:** MapTiler API key for map visualization with Leaflet.

**How to get:**
1. Sign up at https://www.maptiler.com/
2. Navigate to Account > Keys
3. Create a new API key
4. Copy and paste into .env file

**Usage:**
- Interactive map with POI markers
- Route visualization with polylines
- Marker clustering for performance
- Category-based markers (restaurant, attraction, hotel, etc.)

**Features:**
- Outdoor map tiles optimized for Cappadocia
- Custom marker icons with category colors
- Popup with images and descriptions
- Add/remove places from route via map

---

## Optional Environment Variables

### OpenAI Rate Limiting
```bash
VITE_OPENAI_RATE_LIMIT_MAX=10
VITE_OPENAI_RATE_LIMIT_WINDOW=3600000
```
**Description:** Configure client-side rate limiting for OpenAI API calls.

**Defaults:**
- Max requests: 10
- Window: 3600000ms (1 hour)

---

## Example .env File

```bash
# Clerk Authentication (REQUIRED)
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

# OpenAI Configuration
VITE_OPENAI_API_KEY=sk-proj-...

# MapTiler Configuration
VITE_MAPTILER_API_KEY=qkmdHs3dr0gUcmKEW3rK
VITE_MAPTILER_STYLE_URL=https://api.maptiler.com/maps/019c7033-5c53-7c2d-916e-711c182440f0/style.json

# Optional: OpenAI Rate Limiting
VITE_OPENAI_RATE_LIMIT_MAX=10
VITE_OPENAI_RATE_LIMIT_WINDOW=3600000

# Supabase Configuration (already configured)
VITE_SUPABASE_URL=...
VITE_SUPABASE_ANON_KEY=...
```

---

## Security Notes

1. **Never commit .env files to version control**
2. **Use different API keys for development and production**
3. **Rotate API keys regularly**
4. **Monitor API usage to prevent unexpected costs**
5. **OpenAI API calls are rate-limited on both client and server side**

---

## Cost Estimation

### OpenAI API Costs
- GPT-4: $0.03 / 1K tokens (input), $0.06 / 1K tokens (output)
- Average route generation: ~2000 tokens
- Cost per route: ~$0.18
- With 10 requests/hour limit: Max $1.80/hour per user

### MapTiler Costs
- Free tier: 100,000 tile requests/month
- Paid plan: $49/month for 1,000,000 requests
- Typical usage: ~1000 requests per user session

---

## Troubleshooting

### OpenAI API Issues
- **Error: "OpenAI API key is not configured"**
  - Check if VITE_OPENAI_API_KEY is set in .env
  - Restart development server after adding .env variables

- **Error: "Rate limit exceeded"**
  - Wait for the rate limit window to reset (shown in error message)
  - Adjust VITE_OPENAI_RATE_LIMIT_MAX if needed

### MapTiler Issues
- **Map not loading**
  - Check if VITE_MAPTILER_API_KEY is valid
  - Verify VITE_MAPTILER_STYLE_URL is correct
  - Check browser console for CORS errors

- **Markers not showing**
  - Ensure POI data is loaded from database
  - Check if latitude/longitude values are valid
  - Verify marker cluster group is initialized

---

## Development vs Production

### Development
```bash
VITE_OPENAI_API_KEY=sk-proj-dev-...
VITE_MAPTILER_API_KEY=dev-key-...
```

### Production
```bash
VITE_OPENAI_API_KEY=sk-proj-prod-...
VITE_MAPTILER_API_KEY=prod-key-...
```

Use separate API keys for each environment to:
- Track usage separately
- Prevent development testing from affecting production quotas
- Easily rotate keys if compromised
