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

Route Generation System - Quick Integration Guide

🚀 Quick Start

1. Add OpenAI API Key

Add your OpenAI API key to .env:

VITE_OPENAI_API_KEY=sk-your-api-key-here

2. Integrate MapTiler Map

Replace existing map component in TripPlanner:

import { MapTilerMap } from '@/components/TripPlanner/Map/MapTilerMap';
import { useRouteStore } from '@/store/route-store';
import { getAllCappadociaPOIs } from '@/services/poi-service';

// In your component
const { allPOIs, setAllPOIs } = useRouteStore();

// Load POIs on mount
useEffect(() => {
  const loadPOIs = async () => {
    const pois = await getAllCappadociaPOIs();
    setAllPOIs(pois);
  };
  loadPOIs();
}, []);

// Render map
<MapTilerMap
  places={tripPlaces}
  allPOIs={allPOIs}
  center={[38.6431, 34.8289]}
  zoom={11}
/>

3. Add Route Generator Button

import { RouteGeneratorWizard } from '@/components/TripPlanner/RouteGenerator';
import { useState } from 'react';

const [showRouteGenerator, setShowRouteGenerator] = useState(false);

// Button
<Button
  onClick={() => setShowRouteGenerator(true)}
  className="fixed bottom-6 right-6 rounded-full shadow-lg"
  size="lg"
>
  <Sparkles className="mr-2 h-5 w-5" />
  Generate Personalized Route
</Button>

// Wizard
<RouteGeneratorWizard
  open={showRouteGenerator}
  onClose={() => setShowRouteGenerator(false)}
  onComplete={(route) => {
    // Add route places to trip
    route.days.forEach((day, dayIndex) => {
      day.places.forEach((place) => {
        // Add place to trip day
        addPlaceToTripDay(dayIndex + 1, place);
      });
    });
    setShowRouteGenerator(false);
    toast.success('Route added to your trip!');
  }}
/>

📦 Available Components

MapTilerMap

<MapTilerMap
  places={Place[]}          // Places in route
  allPOIs={POI[]}          // All available POIs
  center={[lat, lng]}      // Map center (optional)
  zoom={number}            // Zoom level (optional)
  className={string}       // CSS class (optional)
/>

RouteGeneratorWizard

<RouteGeneratorWizard
  open={boolean}                              // Show/hide wizard
  onClose={() => void}                        // Close handler
  onComplete={(route: RouteRecommendation) => void}  // Success handler
/>

🔧 Utility Functions

Route Optimizer

import { optimizeRoute, calculateTotalDistance, getRouteStatistics } from '@/utils/route-optimizer';

// Optimize places by distance
const optimized = optimizeRoute(places, {
  maxDurationMinutes: 480, // 8 hours
  priorityWeight: 0.5
});

// Calculate distance
const distance = calculateTotalDistance(places);

// Get statistics
const stats = getRouteStatistics(places);
// Returns: { totalDistance, totalTravelTime, totalActivityTime, totalTime }

Map Interactions

import { addPOIToRoute, removePlaceFromRoute, isPlaceInRoute } from '@/utils/map-interactions';

// Add POI to route
await addPOIToRoute(poiId);

// Remove place from route
removePlaceFromRoute(placeId);

// Check if place is in route
const inRoute = isPlaceInRoute(placeId);

POI Service

import { getAllCappadociaPOIs, getPOIById, getPOIsByCategory, searchPOIs } from '@/services/poi-service';

// Get all POIs
const allPOIs = await getAllCappadociaPOIs();

// Get single POI
const poi = await getPOIById(id);

// Get by category
const restaurants = await getPOIsByCategory('restaurant');

// Search
const results = await searchPOIs('Göreme');

🎨 Customization

Change Map Style

Edit MapTilerMap.tsx:

const MAPTILER_STYLE = 'outdoor-v2'; // or 'streets-v2', 'satellite', etc.

Modify Interests

Edit PreferencesStep.tsx:

const INTERESTS = [
  { id: 'custom', label: 'Custom Interest', icon: '🎯' },
  // Add more interests
];

Adjust Rate Limits

Edit api-rate-limiter.ts:

export const openaiRateLimiter = new RateLimiter({
  maxRequests: 20,        // Increase limit
  windowMs: 60 * 60 * 1000, // 1 hour
});

Customize Marker Icons

Edit MapTilerMap.tsx getCategoryIcon() function:

const iconConfig = {
  restaurant: { color: '#FF6347', icon: '🍽️' },
  custom: { color: '#YOUR_COLOR', icon: '🎯' },
  // Add more categories
};

🔐 Security

Rate Limiting

• OpenAI: 10 requests/hour per user
• MapTiler: 100 requests/minute per user
• Automatic cleanup of expired entries

API Key Protection

• OpenAI key stored in environment variables
• Never exposed to client (use Edge Functions for production)
• Rate limiter prevents abuse

🐛 Troubleshooting

Map Not Loading

1. Check MapTiler API key in .env
2. Verify internet connection
3. Check browser console for errors
4. Ensure Leaflet CSS is imported

Route Generation Fails

1. Check OpenAI API key is set
2. Verify API key has credits
3. Check rate limit not exceeded
4. Review browser console for errors

POIs Not Showing

1. Verify places exist in database
2. Check POI service returns data
3. Ensure setAllPOIs() is called
4. Check map bounds include POIs

Markers Not Clickable

1. Verify map-interactions.ts is imported in main.tsx
2. Check global functions are defined
3. Ensure popup HTML is correct
4. Test on different browsers

📊 Monitoring

Check API Usage

import { openaiRateLimiter } from '@/utils/api-rate-limiter';

// Get remaining requests
const remaining = openaiRateLimiter.getRemainingRequests(userId);

// Get reset time
const resetTime = openaiRateLimiter.getResetTime(userId);

Database Queries

-- Check generated routes
SELECT * FROM generated_routes WHERE user_id = 'user-id';

-- Check API usage
SELECT * FROM api_usage WHERE user_id = 'user-id' ORDER BY created_at DESC;

🎯 Best Practices

1. Load POIs Once: Load POIs on component mount, not on every render
2. Debounce Map Updates: Avoid updating map too frequently
3. Cache Routes: Store generated routes in database
4. Error Boundaries: Wrap components in error boundaries
5. Loading States: Show loading indicators during API calls
6. User Feedback: Use toast notifications for actions
7. Mobile First: Test on mobile devices
8. Accessibility: Ensure keyboard navigation works

📚 Resources

• MapTiler Docs
• Leaflet Docs
• OpenAI API Docs
• Leaflet.markercluster

🆘 Support

For issues or questions:

1. Check implementation summary: ROUTE_GENERATION_IMPLEMENTATION.md
2. Review component source code
3. Check browser console for errors
4. Test with sample data
5. Verify environment variables

✅ Checklist

Before deploying:

• OpenAI API key configured
• MapTiler API key verified
• Database migrations applied
• POIs loaded successfully
• Map renders correctly
• Route generation works
• Rate limiting active
• Error handling tested
• Mobile responsive
• Loading states working
• Toast notifications showing
• Lint checks passed