# arsalanyavari/fl-wireless architecture

> Architecture diagram of the GitHub repository arsalanyavari/fl-wireless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arsalanyavari/fl-wireless
- Repository: https://github.com/arsalanyavari/fl-wireless

## Overview

##### Project type and purpose
- This is a research-oriented Python implementation of a federated-learning (FL) framework over wireless channels, based on the IEEE paper “A Joint Learning and Communications Framework for Federated Learning over Wireless Networks.”
- It includes three main concerns: (a) FL simulation (train.py + log.py), (b) configuration management (config.py / config.toml), (c) result visualization (codes_draw_paper_plots/*.py).

##### File structure
- Top level:
– train.py: entry point for running simulations
– config.py & config.toml: programmatic and TOML-based config definitions
– log.py: logging utilities for metrics and events
– codes_draw_paper_plots/: scripts to load logs and produce paper-style plots (MNIST, LR experiments)
– data/MNIST/raw/: raw data files for local client datasets
- No explicit “src” or “backend/frontend” split—this is a single-process simulation engine.

##### README for technical stack
- Pure Python (3.8–3.10), managed by Poetry (preferred) or venv + requirements.txt
- Dependencies (likely numpy, torch or TensorFlow, toml, matplotlib)
- No external microservices—everything runs locally.

##### Break down the system into components and relationships
a. Main components:
1. Configuration Module
– config.py (defines Config classes)
– config.toml (user-editable parameters: number of clients, wireless channel settings, learning rates, dataset paths)
2. Data Storage
– data/MNIST/raw: local dataset shards for each simulated client
3. FL Simulation Engine (train.py orchestrates everything)
– Data Loader (reads MNIST, partitions among clients)
– Client Agents (perform local training loops)
– Wireless Channel Simulator (applies channel effects, SNR, path loss per round)
– Aggregation Server (averages client updates)
4. Logging Subsystem (log.py)
– Collects metrics per round: loss, accuracy, channel metrics
– Writes to disk or memory buffers
5. Plotting Utilities (codes_draw_paper_plots/*.py)
– Read log outputs
– Generate training curves (MNIST, logistic regression) for paper figures
6. Dependency/Environment Manager
– Poetry or venv + requirements.txt
b. Relationships & interactions:
- Configuration → FL Simulation Engine (train.py reads config)
- Data Storage → Data Loader → Client Agents
- Client Agents ↔ Wireless Channel Simulator → Aggregation Server
- Aggregation Server → updated global model → Client Agents (next round)
- FL Simulation Engine → Logging Subsystem → log files
- Plotting Utilities → read log files → output figures
- Poetry/venv → installs dependencies → supports all other modules
c. Architectural patterns/design principles:
- Layered architecture: Configuration → Core Simulation → Logging → Visualization
- Separation of concerns: simulation logic decoupled from plotting
- Extensibility points: channel model, client count, dataset type—all passed via config
d. Key technologies:
- Python 3.8–3.10
- toml or Python dataclasses for config
- numpy/torch (implicit ML backend)
- matplotlib or similar for plotting
- Poetry / virtualenv for dependency management

##### Summary of essential elements
- Clearly label: Config, Data Storage, FL Engine (with its internal blocks), Logger, Plotter, Environment Manager
- “round-trip” of federated updates through the wireless channel to the server and back

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Environment"
        ConfigModule["Configuration Module"]:::config
        ConfigFileTOML["config.toml"]:::config
        Requirements["requirements.txt"]:::config
    end

    subgraph "Data Storage"
        RawData["data/MNIST/raw"]:::data
    end

    subgraph "FL Simulation Engine"
        Train["train.py"]:::core
        DataLoader["Data Loader"]:::core
        ClientAgents["Client Agents"]:::core
        ChannelSim["Wireless Channel Simulator"]:::core
        Aggregation["Aggregation Server"]:::core
    end

    Logger["Logging Subsystem"]:::data

    subgraph "Plotting Utilities"
        Plot1["train_mnist_plot_1.py"]:::viz
        Plot2["train_mnist_plot_2.py"]:::viz
        Plot3["train_mnist_plot_3.py"]:::viz
        Plot4["train_LR_plot_1.py"]:::viz
        Plot5["train_LR_plot_2.py"]:::viz
        Plot6["train_LR_plot_3.py"]:::viz
    end

    ConfigModule -->|uses| Train
    ConfigFileTOML -->|loads| Train
    Requirements -.->|installs deps for| Train

    RawData -->|reads| DataLoader
    Train -->|orchestrates| DataLoader
    DataLoader -->|provides data to| ClientAgents
    ClientAgents -->|sends updates via| ChannelSim
    ChannelSim -->|forwards updates to| Aggregation
    Aggregation -->|broadcasts new model to| ClientAgents

    Train -->|logs metrics to| Logger
    Logger -->|provides logs to| Plot1
    Logger -->|provides logs to| Plot2
    Logger -->|provides logs to| Plot3
    Logger -->|provides logs to| Plot4
    Logger -->|provides logs to| Plot5
    Logger -->|provides logs to| Plot6

    classDef core fill:#bee3f8,stroke:#3182ce
    classDef config fill:#c6f6d5,stroke:#2f855a
    classDef data fill:#fefcbf,stroke:#d69e2e
    classDef viz fill:#e9d8fd,stroke:#6b46c1

    click ConfigModule "https://github.com/arsalanyavari/fl-wireless/blob/main/config.py"
    click ConfigFileTOML "https://github.com/arsalanyavari/fl-wireless/blob/main/config.toml"
    click Requirements "https://github.com/arsalanyavari/fl-wireless/blob/main/requirements.txt"
    click RawData "https://github.com/arsalanyavari/fl-wireless/tree/main/data/MNIST/raw/"
    click Train "https://github.com/arsalanyavari/fl-wireless/blob/main/train.py"
    click Logger "https://github.com/arsalanyavari/fl-wireless/blob/main/log.py"
    click Plot1 "https://github.com/arsalanyavari/fl-wireless/blob/main/codes_draw_paper_plots/train_mnist_plot_1.py"
    click Plot2 "https://github.com/arsalanyavari/fl-wireless/blob/main/codes_draw_paper_plots/train_mnist_plot_2.py"
    click Plot3 "https://github.com/arsalanyavari/fl-wireless/blob/main/codes_draw_paper_plots/train_mnist_plot_3.py"
    click Plot4 "https://github.com/arsalanyavari/fl-wireless/blob/main/codes_draw_paper_plots/train_LR_plot_1.py"
    click Plot5 "https://github.com/arsalanyavari/fl-wireless/blob/main/codes_draw_paper_plots/train_LR_plot_2.py"
    click Plot6 "https://github.com/arsalanyavari/fl-wireless/blob/main/codes_draw_paper_plots/train_LR_plot_3.py"
```
