A web application that helps users find routes optimized for comfort and accessibility by considering factors like noise exposure, cognitive load, and sensory impact.

• Multiple Route Optimization Modes:

  • Fastest: Minimizes travel time
  • Quietest: Reduces highway exposure and noise
  • Calm: Minimizes turns and decision points for lower cognitive load
  • Scenic: Prefers pleasant, less urban routes

• Real-time Autocomplete Search: Get location suggestions as you type (powered by Mapbox Geocoding API)

• Interactive Map: Visualize routes and toggle between options

• Route Details: View duration, distance, and comfort scores for each route

• Location: ./ root directory
• Tech: React 19, TypeScript, Tailwind CSS, ShadCN UI, Mapbox GL
• Communicates with backend Python API via Next.js API routes

• Location: ./backend directory
• Tech: FastAPI, Uvicorn, Mapbox Directions API
• Runs on http://localhost:8000 by default

• Node.js 20+
• Python 3.9+
• Mapbox API token (included in .env)

# Start both frontend and backend
docker compose -f docker-compose.dev.yml up --build

Frontend will be available at http://localhost:3000 Backend will be available at http://localhost:8000

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

# From root directory
pnpm install
pnpm dev

The frontend will be available at http://localhost:3000

Frontend (.env.local):

BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here

Backend (backend/.env):

MAPBOX_TOKEN=your_mapbox_token_here

1. Search: Enter an origin and destination using the autocomplete search

   • The frontend calls /api/geocode?q=<query> which fetches real Mapbox suggestions

2. Route Finding: Click "Get Routes"

   • Frontend calls /api/route?origin=...&destination=...&mode=...
   • Next.js API proxies this to the Python backend
   • Backend geocodes locations and fetches multiple route alternatives from Mapbox Directions API

3. Route Scoring: Backend analyzes routes

   • Extracts features like turns, highway exposure, intersections, speed
   • Applies mode-specific weights (quietest, fastest, calm, scenic)
   • Returns ranked routes with explanations

4. Visualization: Routes display on the map

   • Selected route highlighted in green
   • Other routes shown in light gray
   • Can toggle between modes to see how priorities change

GET /api/geocode

• Query: q (search string)
• Returns: Array of location suggestions with coordinates

GET /api/route

• Query: origin, destination, mode (fastest|quietest|least_overwhelming|scenic)
• Returns: Multiple routes with scores, badges, and GeoJSON geometries

GET /api/route

• Query: origin, destination, mode
• Returns: Scored and ranked routes with detailed analysis

Backend not connecting:

• Ensure backend is running on http://localhost:8000
• Check BACKEND_URL in .env.local
• Check browser console for error messages

No location suggestions appearing:

• Verify NEXT_PUBLIC_MAPBOX_TOKEN is set in .env.local
• Try typing 2+ characters
• Check network tab in DevTools for /api/geocode requests

Routes not showing on map:

• Verify Mapbox token is valid
• Check that backend successfully geocoded the locations
• Look at browser console for errors

• Frontend auto-connects to backend; no manual API configuration needed
• Autocomplete has 300ms debounce to avoid excessive API calls
• Map automatically fits to show all route options
• Error messages display helpful diagnostic info