trip-planner/docs/plans/2026-08-18-implement-leaflet-frontend.md

Implement Leaflet + OpenStreetMap Frontend

Overview

• Add a complete frontend web interface using Leaflet + OpenStreetMap tiles for route visualization
• Provide a search form for route parameters (from city, to city, date)
• Display found routes in a list with duration, transfers, and cost
• Render route geometry as GeoJSON on an interactive map
• Real segments displayed as solid lines with color by transport type
• Synthetic segments displayed as dashed lines
• Transfer points displayed as markers with popup information

Context

• Files/components involved:
  • static/index.html - main HTML page with Leaflet + OSM integration
  • static/styles.css - CSS styling for the frontend
  • static/app.js - JavaScript for search form, API calls, and map rendering
  • cmd/api/main.go - update to serve static files and the frontend
• Related patterns found:
  • GeoJSON FeatureCollection response from /v1/routes/{search_id}/{route_id}/geojson
  • LineString features with properties: transport, transport_type, kind, synthetic, duration, cost, is_transfer, stroke_color, stroke_width, stroke_dasharray
  • Point features for transfer markers with properties: marker_type, title, connection_time, connection_time_formatted, transfer_type, is_transfer, stroke_color, stroke_width
• Dependencies identified:
  • Leaflet 1.9.4 (CSS and JS from CDN)
  • OpenStreetMap tiles

Development Approach

• Testing approach: Regular (code first, then verify)
• Complete each task fully before moving to the next
• Make small, focused changes
• CRITICAL: ensure all frontend files are properly linked and functional
• Maintain backward compatibility with existing API endpoints

Testing Strategy

• Manual testing: Test search form, route list, map rendering, and popup interactions
• UI/UX testing: Verify responsive layout, loading states, error handling

Progress Tracking

• Mark completed items with [x] immediately when done
• Add newly discovered tasks with ➕ prefix
• Document issues/blockers with ⚠️ prefix
• Update plan if implementation deviates from original scope
• Keep plan in sync with actual work done

What Goes Where

• Implementation Steps ([ ] checkboxes): tasks achievable within this codebase - frontend files, Go server updates
• Post-Completion (no checkboxes): items requiring external action - manual testing in browser

Implementation Steps

Task 1: Create static directory and HTML structure

• create static/ directory
• create static/index.html with Leaflet + OSM integration and search form
• create static/styles.css with styling for layout, routes list, and map
• create static/app.js with API calls and map rendering logic

Task 2: Update Go server to serve static files

• update cmd/api/main.go to serve static files from static/ directory
• add route for /static/* to serve CSS, JS, and other assets
• add route for / or /index.html to serve the frontend

Task 3: Verify frontend functionality

• verify search form works and calls /v1/routes/search endpoint (manual test - skipped, not automatable)
• verify routes list displays correctly with duration, transfers, cost (manual test - skipped, not automatable)
• verify map renders with Leaflet + OpenStreetMap tiles (manual test - skipped, not automatable)
• verify GeoJSON is fetched and rendered on the map (manual test - skipped, not automatable)
• verify transfer markers have popups with connection info (manual test - skipped, not automatable)

Technical Details

• Leaflet CSS: https://unpkg.com/leaflet@1.9.4/dist/leaflet.css
• Leaflet JS: https://unpkg.com/leaflet@1.9.4/dist/leaflet.js
• OpenStreetMap tiles: https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
• GeoJSON rendering: use L.geoJSON() with custom style functions for real vs synthetic edges
• Transport colors: plane = #ff9800 (orange), train = #1976d2 (blue), bus = #cddc39 (lime)

Post-Completion

Items requiring manual intervention or external systems - no checkboxes, informational only

Manual verification:

• Test search form in browser
• Verify map renders correctly with routes
• Test popup interactions for transfer points
• Verify responsive layout on different screen sizes