# tayebbb/aust_hackathon_26 architecture

> Architecture diagram of the GitHub repository tayebbb/aust_hackathon_26, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tayebbb/aust_hackathon_26
- Repository: https://github.com/tayebbb/aust_hackathon_26

## Overview

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: [`backend/routes`](https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/backend/routes) (Routes), [`backend/services/routing_engine.py`](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/routing_engine.py) (Routing Engine), [`backend/main.py`](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/main.py) (main.py), [`backend/services/graph_service.py`](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/graph_service.py) (Graph Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["main.py<br/>app bootstrap<br/>[main.py]"]
  node_backend_routes["Routes"]
  node_backend_services["Services"]
  node_backend_routing_engine{{"Routing Engine<br/>route algo<br/>[routing_engine.py]"}}
  node_backend_multimodal{{"Multi Dijkstra<br/>state-space search"}}
  node_backend_graph_service[("Graph Service<br/>graph state<br/>[graph_service.py]")]
  node_backend_anomaly["Anomaly Service<br/>incident overlay<br/>[anomaly_service.py]"]
  node_backend_traffic["Traffic Service<br/>async jobs"]
  node_backend_ml_integration["ML Client<br/>service client<br/>[ml_integration.py]"]
  node_backend_osm_builder["OSM Builder<br/>graph import"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App<br/>spa shell<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>page layer"]
  node_frontend_map(("Map View<br/>map UI<br/>[MapView.jsx]"))
  node_frontend_panels["Panels<br/>controls"]
  node_frontend_api["API Client<br/>http client<br/>[api.js]"]
end

subgraph group_ml["ML Service"]
  node_ml_predict["Predict API<br/>prediction api<br/>[predict.py]"]
  node_ml_preprocess["Preprocess<br/>feature prep<br/>[preprocess.py]"]
  node_ml_train["Train<br/>[train.py]"]
end

subgraph group_infra["Infra"]
  node_infra_compose["Compose<br/>runtime stack<br/>[docker-compose.yml]"]
  node_infra_ci["CI/CD<br/>pipeline<br/>[ci.yml]"]
end

node_backend_main -->|"mounts"| node_backend_routes
node_backend_main -->|"initializes"| node_backend_services
node_backend_main -->|"loads graph"| node_backend_osm_builder
node_backend_routes -->|"route APIs"| node_backend_routing_engine
node_backend_routes -->|"anomaly APIs"| node_backend_anomaly
node_backend_routes -->|"traffic APIs"| node_backend_traffic
node_backend_routes -->|"graph APIs"| node_backend_graph_service
node_backend_routes -->|"health/validate"| node_backend_ml_integration
node_backend_routing_engine -->|"uses"| node_backend_multimodal
node_backend_routing_engine -->|"reads graph"| node_backend_graph_service
node_backend_routing_engine -->|"applies overlay"| node_backend_anomaly
node_backend_routing_engine -->|"enriches"| node_backend_ml_integration
node_backend_multimodal -->|"mode graph"| node_backend_graph_service
node_backend_anomaly -->|"mutates"| node_backend_graph_service
node_backend_traffic -->|"predicts"| node_backend_ml_integration
node_backend_traffic -->|"polls via"| node_backend_routes
node_backend_graph_service -->|"built from"| node_backend_osm_builder
node_frontend_app -->|"composes"| node_frontend_pages
node_frontend_pages -->|"renders"| node_frontend_map
node_frontend_pages -->|"controls"| node_frontend_panels
node_frontend_panels -->|"calls"| node_frontend_api
node_frontend_map -->|"fetches"| node_frontend_api
node_frontend_api -->|"http"| node_backend_routes
node_backend_ml_integration -->|"http"| node_ml_predict
node_ml_predict -->|"uses"| node_ml_preprocess
node_ml_train -->|"trains on"| node_ml_preprocess
node_infra_compose -->|"runs"| node_backend_main
node_infra_compose -->|"runs"| node_frontend_app
node_infra_compose -->|"runs"| node_ml_predict
node_infra_ci -->|"tests/builds"| node_backend_main
node_infra_ci -->|"tests/builds"| node_frontend_app
node_infra_ci -->|"tests/builds"| node_ml_predict

click node_backend_main "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/main.py"
click node_backend_routes "https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/backend/routes"
click node_backend_services "https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/backend/services"
click node_backend_routing_engine "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/routing_engine.py"
click node_backend_multimodal "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/multimodal_dijkstra.py"
click node_backend_graph_service "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/graph_service.py"
click node_backend_anomaly "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/anomaly_service.py"
click node_backend_traffic "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/traffic_jam_service.py"
click node_backend_ml_integration "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/ml_integration.py"
click node_backend_osm_builder "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/utils/osm_graph_builder.py"
click node_frontend_app "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/frontend/src/pages"
click node_frontend_map "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/frontend/src/components/MapView.jsx"
click node_frontend_panels "https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/frontend/src/components"
click node_frontend_api "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/frontend/src/services/api.js"
click node_ml_predict "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/ml/predict.py"
click node_ml_preprocess "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/ml/preprocess.py"
click node_ml_train "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/ml/train.py"
click node_infra_compose "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/docker-compose.yml"
click node_infra_ci "https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_routes,node_backend_services,node_backend_routing_engine,node_backend_multimodal,node_backend_graph_service,node_backend_anomaly,node_backend_traffic,node_backend_ml_integration,node_backend_osm_builder toneBlue
class node_frontend_app,node_frontend_pages,node_frontend_map,node_frontend_panels,node_frontend_api toneAmber
class node_ml_predict,node_ml_preprocess,node_ml_train toneMint
class node_infra_compose,node_infra_ci toneRose
```

## Components

### Backend

FastAPI orchestration, routing, graph state, anomalies, and traffic prediction integration.

- [main.py](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/main.py): app bootstrap · Starts the API, loads the road graph, initializes services, and launches background work. · `backend/main.py`
- [Routes](https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/backend/routes): api routes · Thin HTTP surface for health, routing, anomalies, traffic, graph, auth, and v2 endpoints. · `backend/routes`
- [Services](https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/backend/services): domain services · Core business logic for routing, graph handling, anomalies, traffic jobs, auth, and ML integration. · `backend/services`
- [Routing Engine](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/routing_engine.py): route algo · Single-modal and multimodal route computation entry point. · `backend/services/routing_engine.py`
- [Multi Dijkstra](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/multimodal_dijkstra.py): state-space search · Multimodal Dijkstra over node and mode states, including fallback sequencing. · `backend/services/multimodal_dijkstra.py`
- [Graph Service](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/graph_service.py): graph state · Owns the in-memory OSM graph, mode constraints, nearest-node lookup, and cached subgraphs. · `backend/services/graph_service.py`
- [Anomaly Service](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/anomaly_service.py): incident overlay · Applies live incident overlays by changing weights or disabling vehicle access. · `backend/services/anomaly_service.py`
- [Traffic Service](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/traffic_jam_service.py): async jobs · Tracks route jobs and polls prediction lifecycle for congestion intelligence. · `backend/services/traffic_jam_service.py`
- [ML Client](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/services/ml_integration.py): service client · Optional backend client for calling the separate prediction service. · `backend/services/ml_integration.py`
- [OSM Builder](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/backend/utils/osm_graph_builder.py): graph import · 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](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/frontend/src/App.jsx): spa shell · React application root and client-side routing. · `frontend/src/App.jsx`
- [Pages](https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/frontend/src/pages): page layer · Landing and map planner page composition. · `frontend/src/pages`
- [Map View](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/frontend/src/components/MapView.jsx): map UI · Renders routes, overlays, and the interactive planning map. · `frontend/src/components/MapView.jsx`
- [Panels](https://github.com/tayebbb/aust_hackathon_26/tree/dev-2/frontend/src/components): controls · Route, mode, comparison, and anomaly controls for planning and incident injection. · `frontend/src/components`
- [API Client](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/frontend/src/services/api.js): http client · Browser-side API wrapper for routing and traffic polling. · `frontend/src/services/api.js`

### ML Service

Standalone traffic-risk prediction microservice.

- [Predict API](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/ml/predict.py): prediction api · Batch prediction endpoint for edge features and traversal-risk output. · `ml/predict.py`
- [Preprocess](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/ml/preprocess.py): feature prep · Feature preparation for model input. · `ml/preprocess.py`
- [Train](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/ml/train.py): training pipeline · Model training workflow and offline experimentation entry point. · `ml/train.py`

### Infra

Container, CI/CD, and runtime support files.

- [Compose](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/docker-compose.yml): runtime stack · Multi-service local and production topology for backend, frontend, ML, databases, and cache. · `docker-compose.yml`
- [CI/CD](https://github.com/tayebbb/aust_hackathon_26/blob/dev-2/.github/workflows/ci.yml): pipeline · GitHub Actions workflows for build, test, and deployment. · `.github/workflows/ci.yml`

## Connections

- 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.
