# manpreet-singh-aiml/aqi-jalandhar architecture

> Architecture diagram of the GitHub repository manpreet-singh-aiml/aqi-jalandhar, 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/manpreet-singh-aiml/aqi-jalandhar
- Repository: https://github.com/manpreet-singh-aiml/aqi-jalandhar

## Overview

FedLSTM-AQI is a command-line research pipeline for preparing Jalandhar air-quality data, computing CPCB-standard AQI labels, and training/evaluating centralized and federated forecasting models. The main path is raw CPCB data through preprocessing and AQI labeling to LSTM or BiLSTM forecasts; federated training additionally uses CPCB and heterogeneous Airveda client data, Paillier-protected output-layer weights, and sample-proportional FedAvg. Source excerpts show the federated orchestration and model details; the README documents the script-level pipeline and capabilities.

Main entry points: [`federated_approach.py`](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py) (Local training), [`bilstm_training.py`](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/bilstm_training.py) (Sensor validation), [`preprocess.py`](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/preprocess.py) (Preprocess data), [`compute_aqi.py`](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/compute_aqi.py) (Compute AQI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_prep["Data Preparation"]
  node_preprocess["Preprocess data<br/>[preprocess.py]"]
  node_filled_data["Filled dataset"]
  node_aqi_compute["Compute AQI<br/>[compute_aqi.py]"]
  node_labeled_data["AQI dataset"]
end

subgraph group_centralized["Centralized Models"]
  node_lstm["LSTM baseline<br/>[lstm_training.py]"]
  node_bilstm["BiLSTM attention<br/>[bilstm_training.py]"]
end

subgraph group_federated["Federated Learning"]
  node_clients["Three FL clients"]
  node_fl_models["LSTM and BiLSTM"]
  node_local_training["Local training"]
  node_paillier["Paillier protection"]
  node_fedavg["FedAvg aggregation"]
  node_global_models["Global models"]
end

subgraph group_evaluation["Evaluation"]
  node_validation["Sensor validation<br/>[bilstm_training.py]"]
  node_metrics["Forecast metrics"]
end

node_cpcb_data["CPCB data"]
node_sensor_data["Airveda sensors"]
node_forecasts["AQI forecasts"]

node_cpcb_data -->|"loads raw data"| node_preprocess
node_preprocess -->|"writes filled data"| node_filled_data
node_filled_data -->|"loads filled data"| node_aqi_compute
node_aqi_compute -->|"writes AQI labels"| node_labeled_data
node_labeled_data -->|"trains baseline"| node_lstm
node_labeled_data -->|"trains baseline"| node_bilstm
node_labeled_data -->|"loads CPCB data"| node_clients
node_sensor_data -->|"loads client data"| node_clients
node_clients -->|"provides client samples"| node_local_training
node_fl_models -->|"creates local models"| node_local_training
node_local_training -->|"encrypts Dense weights"| node_paillier
node_local_training -->|"supplies local weights"| node_fedavg
node_paillier -->|"protects sampled weights"| node_fedavg
node_fedavg -->|"updates global weights"| node_global_models
node_global_models -->|"evaluates predictions"| node_metrics
node_lstm -->|"validates on sensors"| node_validation
node_bilstm -->|"validates on sensors"| node_validation
node_validation -->|"produces predictions"| node_forecasts
node_metrics -->|"reports forecast results"| node_forecasts

click node_preprocess "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/preprocess.py"
click node_aqi_compute "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/compute_aqi.py"
click node_lstm "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/lstm_training.py"
click node_bilstm "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/bilstm_training.py"
click node_clients "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py"
click node_fl_models "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py"
click node_local_training "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py"
click node_paillier "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py"
click node_fedavg "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py"
click node_global_models "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py"
click node_validation "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/bilstm_training.py"
click node_metrics "https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.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_preprocess,node_filled_data,node_aqi_compute,node_labeled_data toneBlue
class node_lstm,node_bilstm toneAmber
class node_clients,node_fl_models,node_local_training,node_paillier,node_fedavg,node_global_models toneMint
class node_validation,node_metrics toneRose
class node_cpcb_data,node_sensor_data,node_forecasts toneIndigo
```

## Components

### Data Preparation

- [Preprocess data](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/preprocess.py): `preprocess.py`
- **Filled dataset**
- [Compute AQI](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/compute_aqi.py): `compute_aqi.py`
- **AQI dataset**

### Centralized Models

- [LSTM baseline](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/lstm_training.py): `lstm_training.py`
- [BiLSTM attention](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/bilstm_training.py): `bilstm_training.py`

### Federated Learning

- [Three FL clients](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`
- [LSTM and BiLSTM](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`
- [Local training](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`
- [Paillier protection](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`
- [FedAvg aggregation](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`
- [Global models](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`

### Evaluation

- [Sensor validation](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/bilstm_training.py): `bilstm_training.py`
- [Forecast metrics](https://github.com/manpreet-singh-aiml/aqi-jalandhar/blob/main/federated_approach.py): `federated_approach.py`

### Other components

- **CPCB data**
- **Airveda sensors**
- **AQI forecasts**

## Connections

- CPCB data → Preprocess data: loads raw data (evidence: `README.md`)
- Preprocess data → Filled dataset: writes filled data (evidence: `README.md`)
- Filled dataset → Compute AQI: loads filled data (evidence: `compute_aqi.py`)
- Compute AQI → AQI dataset: writes AQI labels (evidence: `compute_aqi.py`)
- AQI dataset → LSTM baseline: trains baseline (evidence: `lstm_training.py`)
- AQI dataset → BiLSTM attention: trains baseline (evidence: `bilstm_training.py`)
- AQI dataset → Three FL clients: loads CPCB data (evidence: `federated_approach.py`)
- Airveda sensors → Three FL clients: loads client data (evidence: `federated_approach.py`)
- Three FL clients → Local training: provides client samples (evidence: `federated_approach.py`)
- LSTM and BiLSTM → Local training: creates local models (evidence: `federated_approach.py`)
- Local training → Paillier protection: encrypts Dense weights (evidence: `federated_approach.py`)
- Local training → FedAvg aggregation: supplies local weights (evidence: `federated_approach.py`)
- Paillier protection → FedAvg aggregation: protects sampled weights (evidence: `federated_approach.py`)
- FedAvg aggregation → Global models: updates global weights (evidence: `federated_approach.py`)
- Global models → Forecast metrics: evaluates predictions (evidence: `federated_approach.py`)
- LSTM baseline → Sensor validation: validates on sensors (evidence: `lstm_training.py`)
- BiLSTM attention → Sensor validation: validates on sensors (evidence: `bilstm_training.py`)
- Sensor validation → AQI forecasts: produces predictions (evidence: `README.md`)
- Forecast metrics → AQI forecasts: reports forecast results (evidence: `README.md`)
