# ignite-0/bike-share-demand-forecasting- architecture

> Architecture diagram of the GitHub repository ignite-0/bike-share-demand-forecasting-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ignite-0/bike-share-demand-forecasting-
- Repository: https://github.com/ignite-0/bike-share-demand-forecasting-

## Overview

This repository builds Citi Bike station-level demand forecasts, turns them into stockout alerts and suggested bike moves, and serves forecasts plus an alert track record through an API and dashboard. The documented path runs from trip, weather, and GBFS data through station-hour aggregation, feature construction, forecasting, and decisions. Training, evaluation, explanation, and tuning are supporting modeling capabilities. Several links below rely on the README or SOURCE INDEX; unsampled internals are not assumed to have been inspected.

Main entry points: [`src/models/data.py`](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/data.py) (Model data access), [`src/models/predict.py`](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/predict.py) (Forecast prediction), [`src/ingest/weather.py`](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/weather.py) (Weather ingestion), [`data/raw`](https://github.com/ignite-0/bike-share-demand-forecasting-/tree/main/data/raw) (Raw data archive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_trip_download["Trip download<br/>[download_trips.py]"]
  node_weather_ingest["Weather ingestion<br/>[weather.py]"]
  node_gbfs_collector["GBFS collector<br/>[gbfs_collector.py]"]
  node_station_hour["Station-hour build<br/>[station_hour.py]"]
  node_raw_data["Raw data archive"]
end

subgraph group_modeling["Forecast modeling"]
  node_feature_build["Feature builder<br/>[build.py]"]
  node_model_data["Model data access<br/>[data.py]"]
  node_model_train["Model training<br/>[train.py]"]
  node_model_final["Final model selection<br/>[final.py]"]
  node_model_predict["Forecast prediction<br/>[predict.py]"]
  node_model_evaluate["Model evaluation<br/>[evaluate.py]"]
  node_model_classical["Classical baselines<br/>[classical.py]"]
  node_model_explain["Model explanations<br/>[explain.py]"]
  node_model_tune["Model tuning<br/>[tune.py]"]
end

subgraph group_decisions["Stock decisions"]
  node_rebalance["Stock projection<br/>[rebalance.py]"]
  node_backtest["Alert backtest<br/>[backtest.py]"]
end

subgraph group_serving["Serving and dashboard"]
  node_publisher["Forecast publisher<br/>[publish.py]"]
  node_api["Forecast API<br/>[main.py]"]
  node_dashboard["Streamlit dashboard<br/>[streamlit_app.py]"]
  node_artifact_store["Published artifacts<br/>[publish.py]"]
end

node_trip_source(("Monthly trips"))
node_weather_source(("Weather feeds"))
node_gbfs_source(("Live GBFS"))
node_user(("Dashboard user"))

node_trip_source -->|"provides files"| node_trip_download
node_weather_source -->|"provides weather"| node_weather_ingest
node_gbfs_source -->|"provides status"| node_gbfs_collector
node_trip_download -.->|"saves trips"| node_raw_data
node_weather_ingest -->|"saves weather"| node_raw_data
node_gbfs_collector -->|"archives snapshots"| node_raw_data
node_raw_data -->|"aggregates inputs"| node_station_hour
node_weather_ingest -.->|"joins weather"| node_station_hour
node_station_hour -->|"builds features"| node_feature_build
node_feature_build -->|"writes feature table"| node_model_data
node_model_data -->|"loads training data"| node_model_train
node_model_data -->|"loads training data"| node_model_classical
node_model_data -->|"loads evaluation data"| node_model_evaluate
node_model_data -->|"loads model data"| node_model_explain
node_model_evaluate -->|"scores candidates"| node_model_tune
node_model_train -->|"trains candidates"| node_model_final
node_model_final -->|"supplies models"| node_model_predict
node_feature_build -->|"builds forecast features"| node_model_predict
node_weather_ingest -->|"supplies forecast weather"| node_model_predict
node_model_predict -->|"builds forecasts"| node_publisher
node_gbfs_collector -->|"fetches live status"| node_api
node_model_predict -->|"provides demand forecasts"| node_rebalance
node_api -->|"recommends moves"| node_rebalance
node_rebalance -->|"shares risk scoring"| node_backtest
node_publisher -->|"scores track record"| node_backtest
node_publisher -->|"writes serving files"| node_artifact_store
node_artifact_store -->|"serves forecasts"| node_api
node_user -->|"views results"| node_dashboard
node_dashboard -->|"requests forecast data"| node_api

click node_trip_download "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/download_trips.py"
click node_weather_ingest "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/weather.py"
click node_gbfs_collector "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/gbfs_collector.py"
click node_station_hour "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/station_hour.py"
click node_raw_data "https://github.com/ignite-0/bike-share-demand-forecasting-/tree/main/data/raw"
click node_feature_build "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/features/build.py"
click node_model_data "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/data.py"
click node_model_train "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/train.py"
click node_model_final "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/final.py"
click node_model_predict "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/predict.py"
click node_model_evaluate "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/evaluate.py"
click node_model_classical "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/classical.py"
click node_model_explain "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/explain.py"
click node_model_tune "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/tune.py"
click node_rebalance "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/decision/rebalance.py"
click node_backtest "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/decision/backtest.py"
click node_publisher "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/api/publish.py"
click node_api "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/api/main.py"
click node_dashboard "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/app/streamlit_app.py"
click node_artifact_store "https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/api/publish.py"

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_trip_download,node_weather_ingest,node_gbfs_collector,node_station_hour,node_raw_data,node_user toneBlue
class node_feature_build,node_model_data,node_model_train,node_model_final,node_model_predict,node_model_evaluate,node_model_classical,node_model_explain,node_model_tune toneAmber
class node_rebalance,node_backtest toneMint
class node_publisher,node_api,node_dashboard,node_artifact_store toneRose
class node_trip_source,node_weather_source,node_gbfs_source toneIndigo
```

## Components

### Data ingestion

- [Trip download](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/download_trips.py): `src/ingest/download_trips.py`
- [Weather ingestion](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/weather.py): `src/ingest/weather.py`
- [GBFS collector](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/gbfs_collector.py): `src/ingest/gbfs_collector.py`
- [Station-hour build](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/ingest/station_hour.py): `src/ingest/station_hour.py`
- [Raw data archive](https://github.com/ignite-0/bike-share-demand-forecasting-/tree/main/data/raw): `data/raw`

### Forecast modeling

- [Feature builder](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/features/build.py): `src/features/build.py`
- [Model data access](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/data.py): `src/models/data.py`
- [Model training](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/train.py): `src/models/train.py`
- [Final model selection](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/final.py): `src/models/final.py`
- [Forecast prediction](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/predict.py): `src/models/predict.py`
- [Model evaluation](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/evaluate.py): `src/models/evaluate.py`
- [Classical baselines](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/classical.py): `src/models/classical.py`
- [Model explanations](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/explain.py): `src/models/explain.py`
- [Model tuning](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/models/tune.py): `src/models/tune.py`

### Stock decisions

- [Stock projection](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/decision/rebalance.py): `src/decision/rebalance.py`
- [Alert backtest](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/decision/backtest.py): `src/decision/backtest.py`

### Serving and dashboard

- [Forecast publisher](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/api/publish.py): `src/api/publish.py`
- [Forecast API](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/api/main.py): `src/api/main.py`
- [Streamlit dashboard](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Published artifacts](https://github.com/ignite-0/bike-share-demand-forecasting-/blob/main/src/api/publish.py): `src/api/publish.py`

### Other components

- **Monthly trips**
- **Weather feeds**
- **Live GBFS**
- **Dashboard user**

## Connections

- Monthly trips → Trip download: provides files (evidence: `README.md`)
- Weather feeds → Weather ingestion: provides weather (evidence: `src/ingest/weather.py`)
- Live GBFS → GBFS collector: provides status (evidence: `src/ingest/gbfs_collector.py`)
- Trip download → Raw data archive: saves trips
- Weather ingestion → Raw data archive: saves weather (evidence: `src/ingest/weather.py`)
- GBFS collector → Raw data archive: archives snapshots (evidence: `README.md`)
- Raw data archive → Station-hour build: aggregates inputs (evidence: `src/ingest/station_hour.py`)
- Weather ingestion → Station-hour build: joins weather
- Station-hour build → Feature builder: builds features (evidence: `README.md`)
- Feature builder → Model data access: writes feature table (evidence: `src/models/data.py`)
- Model data access → Model training: loads training data (evidence: `src/models/train.py`)
- Model data access → Classical baselines: loads training data (evidence: `src/models/classical.py`)
- Model data access → Model evaluation: loads evaluation data (evidence: `src/models/evaluate.py`)
- Model data access → Model explanations: loads model data (evidence: `src/models/explain.py`)
- Model evaluation → Model tuning: scores candidates (evidence: `src/models/tune.py`)
- Model training → Final model selection: trains candidates (evidence: `src/models/final.py`)
- Final model selection → Forecast prediction: supplies models (evidence: `src/models/predict.py`)
- Feature builder → Forecast prediction: builds forecast features (evidence: `src/models/predict.py`)
- Weather ingestion → Forecast prediction: supplies forecast weather (evidence: `src/models/predict.py`)
- Forecast prediction → Forecast publisher: builds forecasts (evidence: `src/api/publish.py`)
- GBFS collector → Forecast API: fetches live status (evidence: `src/api/main.py`)
- Forecast prediction → Stock projection: provides demand forecasts (evidence: `src/decision/rebalance.py`)
- Forecast API → Stock projection: recommends moves (evidence: `src/api/main.py`)
- Stock projection → Alert backtest: shares risk scoring (evidence: `src/decision/backtest.py`)
- Forecast publisher → Alert backtest: scores track record (evidence: `src/api/publish.py`)
- Forecast publisher → Published artifacts: writes serving files (evidence: `src/api/publish.py`)
- Published artifacts → Forecast API: serves forecasts (evidence: `src/api/main.py`)
- Dashboard user → Streamlit dashboard: views results (evidence: `README.md`)
- Streamlit dashboard → Forecast API: requests forecast data (evidence: `README.md`)
