38980-vm/app-9w9pd00g5j41/ENVIRONMENT_VARIABLES.md

Environment Variables Configuration

Required Environment Variables

Clerk Authentication Configuration

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 for detailed setup instructions.

---

OpenAI API Configuration

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

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

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

# 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

VITE_OPENAI_API_KEY=sk-proj-dev-...
VITE_MAPTILER_API_KEY=dev-key-...

Production

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