# ravnoor-kaur/traffic-fl architecture

> Architecture diagram of the GitHub repository ravnoor-kaur/traffic-fl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravnoor-kaur/traffic-fl
- Repository: https://github.com/ravnoor-kaur/traffic-fl

## Overview

This research project compares hourly traffic forecasting with a last-hour baseline, centralized GRU training, and Flower-based federated GRU training across four junctions. The workflow runs from traffic data exploration and per-junction preprocessing through model training and test evaluation, then records and compares results. Federated clients train locally and exchange model weights with a FedAvg server. The graph preserves the documented exploration and experiment branches; relationships for unsampled modules are included only where the README or source index supports them.

Main entry points: [`federated/trafficfl/server_app.py`](https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/server_app.py) (FedAvg server), [`src/train_central.py`](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/train_central.py) (Central training), [`federated/trafficfl/client_app.py`](https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/client_app.py) (Junction client), [`src/compare.py`](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/compare.py) (Result comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_explore["Data exploration<br/>[explore.py]"]
  node_prep["Junction preprocessing<br/>[data_prep.py]"]
end

subgraph group_experiments["Training experiments"]
  node_gru["GRU model and training<br/>[model.py]"]
  node_central["Central training<br/>[train_central.py]"]
end

subgraph group_federated["Federated learning"]
  node_task["Federated task helpers<br/>[task.py]"]
  node_client["Junction client<br/>[client_app.py]"]
  node_server["FedAvg server<br/>[server_app.py]"]
end

subgraph group_results["Evaluation and results"]
  node_experiment_log["Experiment log<br/>[model.py]"]
  node_round_log["Round metrics<br/>[server_app.py]"]
  node_compare["Result comparison<br/>[compare.py]"]
  node_result_artifacts["Result artifacts"]
end

node_user(("Researcher"))
node_traffic_csv["Traffic CSV"]
node_flower{{"Flower runtime"}}

node_user -->|"runs exploration"| node_explore
node_traffic_csv -->|"reads data"| node_explore
node_user -->|"runs preprocessing"| node_prep
node_traffic_csv -->|"loads and sorts"| node_prep
node_user -->|"runs experiment"| node_central
node_central -->|"prepares junctions"| node_prep
node_central -->|"trains and evaluates"| node_gru
node_central -->|"records metrics"| node_experiment_log
node_user -->|"starts federation"| node_server
node_server -->|"loads tools and data"| node_task
node_task -->|"prepares junction data"| node_prep
node_task -->|"provides model tools"| node_gru
node_server -->|"starts FedAvg"| node_flower
node_flower -.->|"dispatches rounds"| node_client
node_client -->|"loads local data"| node_task
node_client -->|"trains locally"| node_gru
node_client -->|"returns weights"| node_flower
node_server -->|"writes round metrics"| node_round_log
node_server -->|"logs final metrics"| node_experiment_log
node_user -->|"runs comparison"| node_compare
node_compare -->|"reads results"| node_experiment_log
node_compare -->|"reads rounds"| node_round_log
node_compare -->|"writes tables and charts"| node_result_artifacts
node_explore -->|"saves exploration charts"| node_result_artifacts

click node_explore "https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/explore.py"
click node_prep "https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/data_prep.py"
click node_gru "https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/model.py"
click node_central "https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/train_central.py"
click node_task "https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/task.py"
click node_client "https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/client_app.py"
click node_server "https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/server_app.py"
click node_experiment_log "https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/model.py"
click node_round_log "https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/server_app.py"
click node_compare "https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/compare.py"
click node_result_artifacts "https://github.com/ravnoor-kaur/traffic-fl/tree/main/results"

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_explore,node_prep toneBlue
class node_gru,node_central toneAmber
class node_task,node_client,node_server toneMint
class node_experiment_log,node_round_log,node_compare,node_result_artifacts toneRose
class node_user,node_traffic_csv,node_flower toneIndigo
```

## Components

### Data preparation

- [Data exploration](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/explore.py): `src/explore.py`
- [Junction preprocessing](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/data_prep.py): `src/data_prep.py`

### Training experiments

- [GRU model and training](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/model.py): `src/model.py`
- [Central training](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/train_central.py): `src/train_central.py`

### Federated learning

- [Federated task helpers](https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/task.py): `federated/trafficfl/task.py`
- [Junction client](https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/client_app.py): `federated/trafficfl/client_app.py`
- [FedAvg server](https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/server_app.py): `federated/trafficfl/server_app.py`

### Evaluation and results

- [Experiment log](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/model.py): `src/model.py`
- [Round metrics](https://github.com/ravnoor-kaur/traffic-fl/blob/main/federated/trafficfl/server_app.py): `federated/trafficfl/server_app.py`
- [Result comparison](https://github.com/ravnoor-kaur/traffic-fl/blob/main/src/compare.py): `src/compare.py`
- [Result artifacts](https://github.com/ravnoor-kaur/traffic-fl/tree/main/results): `results`

### Other components

- **Researcher**
- **Traffic CSV**
- **Flower runtime**

## Connections

- Researcher → Data exploration: runs exploration (evidence: `README.md`)
- Traffic CSV → Data exploration: reads data (evidence: `src/explore.py`)
- Researcher → Junction preprocessing: runs preprocessing (evidence: `README.md`)
- Traffic CSV → Junction preprocessing: loads and sorts (evidence: `src/data_prep.py`)
- Researcher → Central training: runs experiment (evidence: `README.md`)
- Central training → Junction preprocessing: prepares junctions (evidence: `src/train_central.py`)
- Central training → GRU model and training: trains and evaluates (evidence: `src/train_central.py`)
- Central training → Experiment log: records metrics (evidence: `src/train_central.py`)
- Researcher → FedAvg server: starts federation (evidence: `README.md`)
- FedAvg server → Federated task helpers: loads tools and data (evidence: `federated/trafficfl/server_app.py`)
- Federated task helpers → Junction preprocessing: prepares junction data (evidence: `federated/trafficfl/task.py`)
- Federated task helpers → GRU model and training: provides model tools (evidence: `federated/trafficfl/task.py`)
- FedAvg server → Flower runtime: starts FedAvg (evidence: `federated/trafficfl/server_app.py`)
- Flower runtime → Junction client: dispatches rounds (evidence: `README.md`)
- Junction client → Federated task helpers: loads local data (evidence: `federated/trafficfl/client_app.py`)
- Junction client → GRU model and training: trains locally (evidence: `federated/trafficfl/client_app.py`)
- Junction client → Flower runtime: returns weights (evidence: `federated/trafficfl/client_app.py`)
- FedAvg server → Round metrics: writes round metrics (evidence: `federated/trafficfl/server_app.py`)
- FedAvg server → Experiment log: logs final metrics (evidence: `federated/trafficfl/server_app.py`)
- Researcher → Result comparison: runs comparison (evidence: `README.md`)
- Result comparison → Experiment log: reads results (evidence: `src/compare.py`)
- Result comparison → Round metrics: reads rounds (evidence: `src/compare.py`)
- Result comparison → Result artifacts: writes tables and charts (evidence: `src/compare.py`)
- Data exploration → Result artifacts: saves exploration charts (evidence: `src/explore.py`)