# vishwakshenansrinivasan/urban-tourism-flow-predictor architecture

> Architecture diagram of the GitHub repository vishwakshenansrinivasan/urban-tourism-flow-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishwakshenansrinivasan/urban-tourism-flow-predictor
- Repository: https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor

## Overview

This is a Chennai transit-and-tourism congestion forecasting product. The workflow synthesizes hourly movement data from transit schedules and coastal weather, engineers temporal features, trains XGBoost, generates 48-hour forecasts with TreeSHAP explanations, stores results, and serves them to a React dashboard and PulseAI assistant. The README documents the major product capabilities; several connections below rely on that documentation or the SOURCE INDEX because the relevant implementation was not excerpted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/App.jsx) (Dashboard app), [`ml_service/forecast_generator.py`](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/forecast_generator.py) (Forecast generator), [`data_pipeline/traffic_synthesizer.py`](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/traffic_synthesizer.py) (Traffic synthesizer), [`data_pipeline/db_storage.py`](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/db_storage.py) (Pipeline storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Data pipeline"]
  node_gtfs["GTFS ingestion<br/>[gtfs_ingest.py]"]
  node_weather["Weather service<br/>[weather_service.py]"]
  node_synth["Traffic synthesizer"]
  node_features["Feature engineering"]
  node_config["City configuration<br/>[config.py]"]
end

subgraph group_forecasting["Forecasting"]
  node_training["Model training<br/>[train_model.py]"]
  node_forecast["Forecast generator"]
  node_shap["TreeSHAP explainability<br/>[explainability.py]"]
end

subgraph group_serving["API and assistant"]
  node_db_access["Database access<br/>[db.js]"]
  node_routes["REST API routes<br/>[routes.js]"]
  node_server["API server<br/>[server.js]"]
  node_assistant["PulseAI engine<br/>[assistantEngine.js]"]
end

subgraph group_dashboard["Dashboard"]
  node_frontend_api["Frontend API client<br/>[api.js]"]
  node_app["Dashboard app<br/>[App.jsx]"]
  node_map["Geospatial map<br/>[GeospatialMap.jsx]"]
  node_drawer["Node detail drawer<br/>[NodeDrawer.jsx]"]
  node_accuracy["Model accuracy suite"]
  node_chat["Assistant interface<br/>[ChatAssistant.jsx]"]
end

subgraph group_storage["Data and artifacts"]
  node_pipeline_store["Pipeline storage<br/>[db_storage.py]"]
  node_model["XGBoost model"]
  node_db[("Urban flow database<br/>[urban_flow.db]")]
end

node_transit_feeds["GTFS transit feeds"]
node_weather_source(("Coastal weather"))
node_transit_user(("Dashboard user"))

node_transit_feeds -->|"provides schedules"| node_gtfs
node_weather_source -.->|"provides conditions"| node_weather
node_gtfs -->|"supplies schedules"| node_synth
node_weather -->|"supplies weather"| node_synth
node_config -->|"configures"| node_gtfs
node_config -->|"configures"| node_weather
node_config -->|"configures"| node_synth
node_synth -->|"provides observations"| node_features
node_synth -->|"stores observations"| node_pipeline_store
node_features -->|"builds training features"| node_training
node_pipeline_store -->|"loads training data"| node_training
node_training -->|"saves model"| node_model
node_training -->|"writes benchmarks"| node_pipeline_store
node_model -->|"loads for prediction"| node_forecast
node_gtfs -->|"provides schedules"| node_forecast
node_weather -->|"provides forecast weather"| node_forecast
node_features -->|"supplies feature logic"| node_forecast
node_forecast -->|"requests attributions"| node_shap
node_forecast -->|"loads history and saves forecasts"| node_pipeline_store
node_pipeline_store -->|"writes forecast data"| node_db
node_db -->|"stores served data"| node_db_access
node_server -->|"registers routes"| node_routes
node_routes -->|"queries data"| node_db_access
node_routes -->|"dispatches questions"| node_assistant
node_assistant -->|"queries telemetry"| node_db_access
node_app -->|"fetches dashboard data"| node_frontend_api
node_frontend_api -->|"calls API endpoints"| node_routes
node_app -->|"renders map"| node_map
node_app -->|"renders node details"| node_drawer
node_app -->|"renders accuracy suite"| node_accuracy
node_app -->|"renders assistant"| node_chat
node_transit_user -->|"uses dashboard"| node_app
node_chat -->|"submits questions"| node_frontend_api

click node_gtfs "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/gtfs_ingest.py"
click node_weather "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/weather_service.py"
click node_synth "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/traffic_synthesizer.py"
click node_features "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/feature_engineer.py"
click node_config "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/config.py"
click node_pipeline_store "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/db_storage.py"
click node_training "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/train_model.py"
click node_model "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/models/xgboost_congestion.json"
click node_forecast "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/forecast_generator.py"
click node_shap "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/explainability.py"
click node_db "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data/urban_flow.db"
click node_db_access "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/db.js"
click node_routes "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/routes.js"
click node_server "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/server.js"
click node_assistant "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/assistantEngine.js"
click node_frontend_api "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/api.js"
click node_app "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/App.jsx"
click node_map "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/GeospatialMap.jsx"
click node_drawer "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/NodeDrawer.jsx"
click node_accuracy "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/ModelAccuracyView.jsx"
click node_chat "https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/ChatAssistant.jsx"

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_gtfs,node_weather,node_synth,node_features,node_config,node_transit_user toneBlue
class node_training,node_forecast,node_shap toneAmber
class node_db_access,node_routes,node_server,node_assistant toneMint
class node_frontend_api,node_app,node_map,node_drawer,node_accuracy,node_chat toneRose
class node_pipeline_store,node_model,node_db,node_transit_feeds,node_weather_source toneIndigo
```

## Components

### Data pipeline

- [GTFS ingestion](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/gtfs_ingest.py): `data_pipeline/gtfs_ingest.py`
- [Weather service](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/weather_service.py): `data_pipeline/weather_service.py`
- [Traffic synthesizer](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/traffic_synthesizer.py): `data_pipeline/traffic_synthesizer.py`
- [Feature engineering](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/feature_engineer.py): `data_pipeline/feature_engineer.py`
- [City configuration](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/config.py): `data_pipeline/config.py`

### Forecasting

- [Model training](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/train_model.py): `ml_service/train_model.py`
- [Forecast generator](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/forecast_generator.py): `ml_service/forecast_generator.py`
- [TreeSHAP explainability](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/ml_service/explainability.py): `ml_service/explainability.py`

### API and assistant

- [Database access](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/db.js): `backend/src/db.js`
- [REST API routes](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/routes.js): `backend/src/routes.js`
- [API server](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/server.js): `backend/src/server.js`
- [PulseAI engine](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/backend/src/assistantEngine.js): `backend/src/assistantEngine.js`

### Dashboard

- [Frontend API client](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Dashboard app](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Geospatial map](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/GeospatialMap.jsx): `frontend/src/components/GeospatialMap.jsx`
- [Node detail drawer](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/NodeDrawer.jsx): `frontend/src/components/NodeDrawer.jsx`
- [Model accuracy suite](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/ModelAccuracyView.jsx): `frontend/src/components/ModelAccuracyView.jsx`
- [Assistant interface](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/frontend/src/components/ChatAssistant.jsx): `frontend/src/components/ChatAssistant.jsx`

### Data and artifacts

- [Pipeline storage](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data_pipeline/db_storage.py): `data_pipeline/db_storage.py`
- [XGBoost model](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/models/xgboost_congestion.json): `models/xgboost_congestion.json`
- [Urban flow database](https://github.com/vishwakshenansrinivasan/urban-tourism-flow-predictor/blob/main/data/urban_flow.db): `data/urban_flow.db`

### Other components

- **GTFS transit feeds**
- **Coastal weather**
- **Dashboard user**

## Connections

- GTFS transit feeds → GTFS ingestion: provides schedules (evidence: `README.md`)
- Coastal weather → Weather service: provides conditions (evidence: `data_pipeline/weather_service.py`)
- GTFS ingestion → Traffic synthesizer: supplies schedules (evidence: `data_pipeline/traffic_synthesizer.py`)
- Weather service → Traffic synthesizer: supplies weather (evidence: `data_pipeline/traffic_synthesizer.py`)
- City configuration → GTFS ingestion: configures (evidence: `data_pipeline/gtfs_ingest.py`)
- City configuration → Weather service: configures (evidence: `data_pipeline/weather_service.py`)
- City configuration → Traffic synthesizer: configures (evidence: `data_pipeline/traffic_synthesizer.py`)
- Traffic synthesizer → Feature engineering: provides observations (evidence: `data_pipeline/feature_engineer.py`)
- Traffic synthesizer → Pipeline storage: stores observations (evidence: `README.md`)
- Feature engineering → Model training: builds training features (evidence: `ml_service/train_model.py`)
- Pipeline storage → Model training: loads training data (evidence: `ml_service/train_model.py`)
- Model training → XGBoost model: saves model (evidence: `README.md`)
- Model training → Pipeline storage: writes benchmarks (evidence: `ml_service/train_model.py`)
- XGBoost model → Forecast generator: loads for prediction (evidence: `README.md`)
- GTFS ingestion → Forecast generator: provides schedules (evidence: `ml_service/forecast_generator.py`)
- Weather service → Forecast generator: provides forecast weather (evidence: `ml_service/forecast_generator.py`)
- Feature engineering → Forecast generator: supplies feature logic (evidence: `ml_service/forecast_generator.py`)
- Forecast generator → TreeSHAP explainability: requests attributions (evidence: `ml_service/forecast_generator.py`)
- Forecast generator → Pipeline storage: loads history and saves forecasts (evidence: `ml_service/forecast_generator.py`)
- Pipeline storage → Urban flow database: writes forecast data (evidence: `README.md`)
- Urban flow database → Database access: stores served data (evidence: `README.md`)
- API server → REST API routes: registers routes (evidence: `backend/src/server.js`)
- REST API routes → Database access: queries data (evidence: `backend/src/routes.js`)
- REST API routes → PulseAI engine: dispatches questions (evidence: `backend/src/routes.js`)
- PulseAI engine → Database access: queries telemetry (evidence: `backend/src/assistantEngine.js`)
- Dashboard app → Frontend API client: fetches dashboard data (evidence: `frontend/src/App.jsx`)
- Frontend API client → REST API routes: calls API endpoints (evidence: `README.md`)
- Dashboard app → Geospatial map: renders map (evidence: `frontend/src/App.jsx`)
- Dashboard app → Node detail drawer: renders node details (evidence: `frontend/src/App.jsx`)
- Dashboard app → Model accuracy suite: renders accuracy suite (evidence: `frontend/src/App.jsx`)
- Dashboard app → Assistant interface: renders assistant (evidence: `frontend/src/App.jsx`)
- Dashboard user → Dashboard app: uses dashboard (evidence: `README.md`)
- Assistant interface → Frontend API client: submits questions (evidence: `README.md`)
