# meghanap1305/a3-ps003-tc122 architecture

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

- Interactive diagram: https://gitdiagram.com/meghanap1305/a3-ps003-tc122
- Repository: https://github.com/meghanap1305/a3-ps003-tc122

## Overview

This repository implements traffic forecasting with a compact MLP, both centralized and simulated federated training, plus preprocessing and evaluation utilities. The main workflow loads and normalizes Parquet traffic windows, trains a model, and evaluates forecasts; the federated path partitions training rows, trains client copies, aggregates updates, and validates the global model. The README is minimal, so the architecture is grounded mainly in the indexed and excerpted source; demo wiring and other unsampled behavior are not inferred.

Main entry points: [`preprocessing/data_loader.py`](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/data_loader.py) (Window loader), [`federated/federated_train.py`](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/federated_train.py) (Federated runner), [`src/train.py`](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/src/train.py) (Central trainer), [`src/model.py`](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/src/model.py) (Traffic MLP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_splits[("Parquet splits")]
  node_loader["Window loader<br/>[data_loader.py]"]
  node_partition["Client partitioning<br/>[partition_data.py]"]
end

subgraph group_central["Centralized forecasting"]
  node_centraltrain["Central trainer<br/>[train.py]"]
  node_model["Traffic MLP<br/>[model.py]"]
end

subgraph group_federated["Federated learning"]
  node_clientdata["Client batch loader"]
  node_clienttrain["Local client trainer<br/>[client.py]"]
  node_runner["Federated runner<br/>[federated_train.py]"]
  node_aggregation["FedAvg aggregation<br/>[fedavg.py]"]
end

subgraph group_analysis["Evaluation and demo"]
  node_baseline["Persistence baseline<br/>[baseline.py]"]
  node_horizon["Horizon metrics"]
  node_evaluation["Global evaluator<br/>[evaluation.py]"]
  node_demo["Demo server<br/>[server.py]"]
  node_demo_ui["Demo interface<br/>[index.html]"]
  node_demo_train["Demo training<br/>[train.py]"]
end

node_analyst(("Operator"))

node_analyst -->|"runs training"| node_centraltrain
node_analyst -->|"creates partitions"| node_partition
node_analyst -->|"runs rounds"| node_runner
node_splits -->|"reads batches"| node_loader
node_loader -->|"provides batches"| node_centraltrain
node_loader -->|"provides batches"| node_baseline
node_loader -->|"provides batches"| node_horizon
node_loader -->|"supplies window logic"| node_clientdata
node_splits -->|"reads training rows"| node_partition
node_partition -.->|"writes client Parquet"| node_clientdata
node_centraltrain -->|"trains"| node_model
node_clientdata -->|"yields batches"| node_clienttrain
node_clienttrain -->|"trains local copy"| node_model
node_runner -->|"invokes clients"| node_clienttrain
node_runner -->|"aggregates updates"| node_aggregation
node_runner -->|"validates global model"| node_evaluation
node_runner -->|"initializes global model"| node_model
node_evaluation -->|"reads validation batches"| node_loader
node_evaluation -->|"evaluates forecasts"| node_model
node_analyst -.->|"opens demo"| node_demo
node_demo -.->|"serves interface"| node_demo_ui
node_demo_train -.->|"uses training history"| node_centraltrain

click node_loader "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/data_loader.py"
click node_partition "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/partition_data.py"
click node_centraltrain "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/src/train.py"
click node_model "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/src/model.py"
click node_baseline "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/baseline.py"
click node_horizon "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/baseline_horizons.py"
click node_clientdata "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/client_data_loader.py"
click node_clienttrain "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/client.py"
click node_runner "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/federated_train.py"
click node_aggregation "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/fedavg.py"
click node_evaluation "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/evaluation.py"
click node_demo "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/demo/server.py"
click node_demo_ui "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/demo/static/index.html"
click node_demo_train "https://github.com/meghanap1305/a3-ps003-tc122/blob/main/demo/src/train.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_splits,node_loader,node_partition toneBlue
class node_centraltrain,node_model toneAmber
class node_clientdata,node_clienttrain,node_runner,node_aggregation toneMint
class node_baseline,node_horizon,node_evaluation,node_demo,node_demo_ui,node_demo_train toneRose
class node_analyst toneIndigo
```

## Components

### Data preparation

- **Parquet splits**
- [Window loader](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/data_loader.py): `preprocessing/data_loader.py`
- [Client partitioning](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/partition_data.py): `partition_data.py`

### Centralized forecasting

- [Central trainer](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/src/train.py): `src/train.py`
- [Traffic MLP](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/src/model.py): `src/model.py`

### Federated learning

- [Client batch loader](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/client_data_loader.py): `federated/client_data_loader.py`
- [Local client trainer](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/client.py): `federated/client.py`
- [Federated runner](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/federated_train.py): `federated/federated_train.py`
- [FedAvg aggregation](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/fedavg.py): `federated/fedavg.py`

### Evaluation and demo

- [Persistence baseline](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/baseline.py): `preprocessing/baseline.py`
- [Horizon metrics](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/preprocessing/baseline_horizons.py): `preprocessing/baseline_horizons.py`
- [Global evaluator](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/federated/evaluation.py): `federated/evaluation.py`
- [Demo server](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/demo/server.py): `demo/server.py`
- [Demo interface](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/demo/static/index.html): `demo/static/index.html`
- [Demo training](https://github.com/meghanap1305/a3-ps003-tc122/blob/main/demo/src/train.py): `demo/src/train.py`

### Other components

- **Operator**

## Connections

- Operator → Central trainer: runs training (evidence: `src/train.py`)
- Operator → Client partitioning: creates partitions (evidence: `partition_data.py`)
- Operator → Federated runner: runs rounds (evidence: `federated/federated_train.py`)
- Parquet splits → Window loader: reads batches (evidence: `preprocessing/data_loader.py`)
- Window loader → Central trainer: provides batches (evidence: `src/train.py`)
- Window loader → Persistence baseline: provides batches (evidence: `preprocessing/baseline.py`)
- Window loader → Horizon metrics: provides batches (evidence: `preprocessing/baseline_horizons.py`)
- Window loader → Client batch loader: supplies window logic (evidence: `federated/client_data_loader.py`)
- Parquet splits → Client partitioning: reads training rows (evidence: `partition_data.py`)
- Client partitioning → Client batch loader: writes client Parquet
- Central trainer → Traffic MLP: trains (evidence: `src/train.py`)
- Client batch loader → Local client trainer: yields batches (evidence: `federated/client.py`)
- Local client trainer → Traffic MLP: trains local copy (evidence: `federated/client.py`)
- Federated runner → Local client trainer: invokes clients (evidence: `federated/federated_train.py`)
- Federated runner → FedAvg aggregation: aggregates updates (evidence: `federated/federated_train.py`)
- Federated runner → Global evaluator: validates global model (evidence: `federated/federated_train.py`)
- Federated runner → Traffic MLP: initializes global model (evidence: `federated/federated_train.py`)
- Global evaluator → Window loader: reads validation batches (evidence: `federated/evaluation.py`)
- Global evaluator → Traffic MLP: evaluates forecasts (evidence: `federated/evaluation.py`)
- Operator → Demo server: opens demo
- Demo server → Demo interface: serves interface
- Demo training → Central trainer: uses training history