How tayebbb/aust_hackathon_26 works
1. What this repo is
GoliTransit is a three-part system: a FastAPI backend for routing and traffic logic, a React/Vite frontend for interactive map-based planning, and a separate ML microservice for asynchronous traffic-risk prediction. The architecture is centered on one in-memory road graph, with dynamic overlays for anomalies and predicted congestion.
2. Backend boundary
The backend is the main orchestration layer. main.py boots the app, creates tables, loads the OSM graph around the AUST area, initializes traffic/ML support, and starts background workers. HTTP entry points are kept thin in backend/routes/, while real logic lives in backend/services/.
3. Core graph model
The routing system is built from an OSMnx-extracted NetworkX MultiDiGraph. The graph preserves road geometry and tags, then adds per-mode constraints such as car/bike/walk/rickshaw/transit access and per-mode travel-time weights. This is the foundational data structure used by all route and graph endpoints.
4. Routing engine
routing_engine.py and multimodal_dijkstra.py implement the route computation layer. The main distinction is between:
- single-modal shortest path,
- multi-modal state-space Dijkstra over (node, mode) states,
- fallback sequential multimodal routing when needed.
This is the key algorithmic boundary in the system and drives both /route and /v2/route.
5. Anomaly subsystem
anomaly_service.py manages live incident injection. Anomalies can target explicit edges or map-derived targets, then apply weight multipliers and optionally disable specific vehicle types. This is an in-memory dynamic overlay on top of the base graph, so new route requests immediately see updated costs.
6. Asynchronous traffic prediction
traffic_jam_service.py is deliberately decoupled from route computation. The /route response returns quickly with a route_id, then background workers predict congestion for the route. Clients poll /traffic/{route_id} to get lifecycle and prediction status. This keeps latency stable while still adding ML-enhanced route intelligence.
7. ML service boundary
The ml/ directory is a separate deployable service with its own Dockerfile and requirements. It exposes /health and /predict, receives batches of edge features, and returns predicted traversal times / risk signals. The backend treats this service as optional: if it is unavailable, routing still works using deterministic fallback behavior.
8. Data and persistence
Persistence is focused on traffic observations rather than route state. The backend uses SQLAlchemy with a database configured for MySQL in the normal runtime, while CI can switch to SQLite for fast testing. There is also Redis wiring in the config/docker setup for runtime caching and async support, though the app’s primary graph state remains in memory.
9. Caching and performance
The architecture relies on several hot-path caches: route response caching, shortest-tree caching, mode-subgraph caching, nearest-node spatial lookup via KDTree, and prediction caches for traffic jobs. These caches matter because the user workflow is interactive and map-driven, so repeated route recomputation must stay fast.
10. Frontend boundary
The frontend is a single-page React app with two major pages: a landing page and a map planner. MapView handles route rendering and overlays; RoutePanel, RouteSelectionPanel, ModeSelector, AnomalyModal, and AnomalyAlert control route calculation and incident injection. The frontend talks only to the backend API and polls traffic status rather than managing route logic locally.
11. API surface
The public backend surface is organized into clear domains:
- health for liveness,
- route for core routing,
- traffic for async ML status,
- anomaly for incident management,
- graph for snapshots/debugging,
- v2 for lower-level node-based routing and validation.
Auth endpoints exist, but the main product flow is routing, anomaly adaptation, and traffic prediction.
12. Deployment and runtime topology
The repo is designed to run as a containerized multi-service stack via Docker Compose: backend, frontend, ML service, MySQL, and Redis. It also includes CI/CD for GitHub Actions, plus deployment paths for Vercel, Azure App Service, and Render. The infrastructure choices are important because the backend depends on startup-time graph loading and on optional external ML availability.
13. Test and validation boundaries
The backend has a substantial test suite covering routing, multimodal Dijkstra behavior, anomaly handling, graph services, and async traffic flow. There is also explicit graph validation in the v2 API, which helps verify that the extracted road graph remains connected and constraint-safe for routing.
Main entry points: routes Routes · routing_engine.py Routing Engine · main.py main.py · graph_service.py Graph Service
Components 20
Backend
FastAPI orchestration, routing, graph state, anomalies, and traffic prediction integration.
- main.py · Starts the API, loads the road graph, initializes services, and launches background work.
backend/main.py - Routes · Thin HTTP surface for health, routing, anomalies, traffic, graph, auth, and v2 endpoints.
backend/routes - Services · Core business logic for routing, graph handling, anomalies, traffic jobs, auth, and ML integration.
backend/services - Routing Engine · Single-modal and multimodal route computation entry point.
backend/services/routing_engine.py - Multi Dijkstra · Multimodal Dijkstra over node and mode states, including fallback sequencing.
backend/services/multimodal_dijkstra.py - Graph Service · Owns the in-memory OSM graph, mode constraints, nearest-node lookup, and cached subgraphs.
backend/services/graph_service.py - Anomaly Service · Applies live incident overlays by changing weights or disabling vehicle access.
backend/services/anomaly_service.py - Traffic Service · Tracks route jobs and polls prediction lifecycle for congestion intelligence.
backend/services/traffic_jam_service.py - ML Client · Optional backend client for calling the separate prediction service.
backend/services/ml_integration.py - OSM Builder · Builds the OSMnx/NetworkX road graph used by routing and validation.
backend/utils/osm_graph_builder.py
Frontend
React/Vite map planner and user interaction layer.
- App · React application root and client-side routing.
frontend/src/App.jsx - Pages · Landing and map planner page composition.
frontend/src/pages - Map View · Renders routes, overlays, and the interactive planning map.
frontend/src/components/MapView.jsx - Panels · Route, mode, comparison, and anomaly controls for planning and incident injection.
frontend/src/components - API Client · Browser-side API wrapper for routing and traffic polling.
frontend/src/services/api.js
ML Service
Standalone traffic-risk prediction microservice.
- Predict API · Batch prediction endpoint for edge features and traversal-risk output.
ml/predict.py - Preprocess · Feature preparation for model input.
ml/preprocess.py - Train · Model training workflow and offline experimentation entry point.
ml/train.py
Connections 32
- main.py → Routes: mounts · Registers HTTP endpoints on startup.
- main.py → Services: initializes · Wires domain services during boot.
- main.py → OSM Builder: loads graph · Builds the base road graph at startup.
- Routes → Routing Engine: route APIs · Route endpoints delegate computation.
- Routes → Anomaly Service: anomaly APIs · Incident endpoints update live overlays.
- Routes → Traffic Service: traffic APIs · Traffic endpoints expose async job status.
- Routes → Graph Service: graph APIs · Graph endpoints read graph snapshots and validation state.
- Routes → ML Client: health/validate · Backend endpoints may surface prediction-service availability.
- Routing Engine → Multi Dijkstra: uses · Multimodal pathfinding is the core algorithmic engine.
- Routing Engine → Graph Service: reads graph · Computes routes against the in-memory road graph.
- Routing Engine → Anomaly Service: applies overlay · Route costs reflect live incident changes.
- Routing Engine → ML Client: enriches · Can attach predicted traffic intelligence when available.
- Multi Dijkstra → Graph Service: mode graph · Search operates over mode-constrained graph state.
- Anomaly Service → Graph Service: mutates · Writes live edge weight and access overrides into graph state.
- Traffic Service → ML Client: predicts · Background jobs request route-edge predictions.
- Traffic Service → Routes: polls via · Clients receive lifecycle updates through traffic endpoints.
- Graph Service → OSM Builder: built from · Graph service is initialized from the OSM builder output.
- App → Pages: composes · App renders page-level flows.
- Pages → Map View: renders · Map planner page centers on the map view.
- Pages → Panels: controls · Planning page assembles route and anomaly controls.
- Panels → API Client: calls · UI actions trigger backend requests and polling.
- Map View → API Client: fetches · Map rendering consumes route and traffic data.
- API Client → Routes: http · Frontend talks to backend API only.
- ML Client → Predict API: http · Backend sends feature batches to the standalone ML service.
- Predict API → Preprocess: uses · Prediction flow shares preprocessing logic.
- Train → Preprocess: trains on · Training pipeline depends on the same feature prep.
- Compose → main.py: runs · Compose brings up the backend service.
- Compose → App: runs · Compose brings up the frontend container.
- Compose → Predict API: runs · Compose brings up the ML service.
- CI/CD → main.py: tests/builds · CI validates backend startup and tests.
- CI/CD → App: tests/builds · CI validates frontend build artifacts.
- CI/CD → Predict API: tests/builds · CI validates the ML service package and runtime.