
Problem
Large events create travel conditions that ordinary route planners do not model well: traffic-management windows, extra delay near the venue, crowd pressure, road restrictions and uncertain Park & Ride access. People travelling from different UK towns need one place to see the normal route, how the event changes it, and whether any live data is actually available.
Architecture
User ↓ GitHub Pages frontend (HTML/CSS/JS + Leaflet) ↓ FastAPI API on Render ↓ JSON event catalogue + SQLite operational store ↓ Geocoding / routing / optional transport and parking providers ↓ Journey intelligence engine ↓ Analysis response
| Layer | Location |
|---|---|
| Event schema | backend/event_model.py |
| Event store | backend/event_store.py |
| Travel engine | backend/travel_engine.py |
| Live transport | backend/live_transport.py |
| Parking | backend/parking_intelligence.py |
| Cache / SQLite | backend/cache.py, backend/db.py |
| API | backend/main.py |

Key technical decisions
- Events are data, not code. A versioned JSON catalogue (
data/events/*.json) is the source of truth, so adding an event means adding data rather than rewriting the engine. - Modelled vs measured is never blurred. The estimate is
round(normal_OSRM_minutes × event_factor + extra_event_delay); live traffic minutes are added only when a real feed returns them. Without a key, live traffic shows as “Unavailable”. - No invented occupancy. Park & Ride shows drive, transfer and total access time; occupancy appears only from an official feed, otherwise “Unknown / No live occupancy feed”.
- Graceful degradation. If the API is unavailable, the static frontend can load local catalogue files and still compute an event-adjusted route with Nominatim and OSRM.
- Operational hygiene. Memory + SQLite cache, Nominatim 429 retry, per-IP rate limiting, structured JSON request logs, and health/readiness endpoints. Cached live data older than 15 minutes is treated as stale.
Data and external services
| Service | Use | Live measured data? |
|---|---|---|
| Nominatim | UK-biased geocoding | No, locations only |
| OSRM | Normal driving route, duration, geometry | No, routing estimate |
| Leaflet / OpenStreetMap | Map display | No |
| National Highways closures API | Structured closures | Only with an API key |
| TfGM alerts / car parks APIs | Alerts and occupancy | Only with an API key |
| TomTom routing | Measured delay vs no-traffic route | Only with an API key |
Limits
- This is a rules- and model-based decision engine, not a machine-learning model.
- On the public deployment no live traffic or parking-occupancy keys are configured, so those layers report “Unavailable” or “Unknown” rather than estimates.
- The fictional
test-event-manchesterrecord exists only to prove the engine reads configuration dynamically; it is not a real event.
What this project demonstrates
- API development: a FastAPI service with health and readiness endpoints, rate limiting and structured logs, deployed on Render.
- Data-driven design: a versioned JSON event catalogue with SQLite as the operational store and cache.
- Integration with external services: Nominatim, OSRM and optional keyed providers, with graceful fallback.
- Honest product behaviour: modelled estimates are never presented as measured live data.
- Testing: automated test modules covering the API, events, journeys, transport and parking.
Written by Emmanuel Abolade, Data Analyst, Business Intelligence Developer and Full-Stack Software Developer based in Hull, UK. Every figure on this page comes from the linked public repository or live demo.