naina-sriv/routeiq

1. Overall shape

RouteIQ is a single Python backend with a browser-based, map-driven frontend. The core runtime is FastAPI in routeiq/main.py, which sits between the UI and the optimization services. The app solves two distinct problems: single-vehicle trip ordering (TSP) and multi-vehicle fleet routing with constraints (VRP).

2. Frontend boundary

The browser UI is a single-page experience rendered from templates/index.html and powered by vanilla JS in static/js/. app.js owns shared map state, stop management, and geocoding interactions; trip.js handles trip-planner mode; fleet.js handles fleet mode, vehicle lists, and route rendering. Leaflet is the map layer, and the frontend talks to the backend only through HTTP fetch() calls.

3. API layer

main.py exposes the service boundary: GET /health, POST /optimize, POST /optimize/fleet, POST /geocode, and POST /reverse-geocode. models.py defines the request/response contracts using Pydantic, while config.py centralizes environment-driven settings such as OSRM, Redis, stop limits, and solver timeouts.

4. Trip optimization flow (TSP)

POST /optimize sends the stop list through a road-distance matrix lookup, then into utils/solver.py. That solver uses Google OR-Tools for a single-vehicle route with fixed start and end nodes. The output is an ordered stop sequence plus per-leg travel times and polylines; if OR-Tools fails or times out, it falls back to a nearest-neighbor route.

5. Fleet optimization flow (VRP)

POST /optimize/fleet follows the same matrix acquisition path, then passes the data to utils/vrp_solver.py. This solver adds the fleet-specific constraints: one route per vehicle, vehicle capacity limits, optional per-stop time windows, and penalties for dropping stops when the fleet cannot cover everything. The response is grouped by vehicle and includes unassigned stops.

6. Road-network dependency

utils/osrm.py is the road-travel layer. It queries OSRM’s /table endpoint for the travel-time matrix and /route for leg polylines. This is the main external dependency that gives the app real road times instead of straight-line estimates. If OSRM is unavailable, the system can fall back to haversine-based estimates, and the response marks that fallback.

7. Caching boundary

utils/cache.py wraps Redis and caches the distance matrix, not the full optimization result. The cache key is derived from the stop coordinates in an order-independent way, so the same set of points reuses the same matrix even if the request order changes. This cache is the main performance boundary: it turns repeated route requests for the same stop set from OSRM-bound to near-instant.

8. Geocoding path

utils/geocoder.py handles forward and reverse geocoding through Nominatim. This is a separate flow from routing: user-entered addresses become coordinates before optimization, and dragged map pins can be converted back into display names. It supports the map UX but does not affect the solver logic.

9. Deployment topology

The repo is designed to run as a small containerized stack defined in docker-compose.yml: the FastAPI app, Redis, and an OSRM backend. In Docker, the app points to the internal OSRM service; outside Docker it can use a public OSRM endpoint. The OSRM container depends on preprocessed map data mounted into a volume, which is an operational prerequisite for routing.

10. Supporting quality and analysis subsystems

tests/ contains unit and integration coverage for the solvers and API behavior, especially route ordering, capacity limits, time windows, and error handling. benchmarks/compare_algorithms.py is a separate analysis tool that compares OR-Tools against a nearest-neighbor baseline using synthetic points and haversine distances. These are not part of the request path, but they validate solver quality and runtime claims.