# sofianebouaziz1/flash-rl architecture

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

- Interactive diagram: https://gitdiagram.com/sofianebouaziz1/flash-rl
- Repository: https://github.com/sofianebouaziz1/flash-rl

## Overview

##### Project type and purpose
- FLASH-RL is a research-oriented federated learning (FL) simulation framework with a reinforcement-learning (RL)-based client-selection engine.
- It orchestrates a central server (with multiple selection policies), many simulated clients, a data-partitioning pipeline, and an RL module to optimize client choice over rounds.

##### Top-level components (from file tree & README)
- Data pipeline
– data_preprocessing/ (raw MobiAct → cleaned streams)
– data_division/ & data_manipulation/ (create non-IID partitions for CIFAR-10, MNIST, MobiAct)
- Client simulation
– clientFL/Client.py (simulated FL client: loads local data, trains model, returns updates)
– clients_info/ (hardware/network profiles per client)
- Server engine
– serverFL/
- Server_FedProx.py (FedAvg/FedProx baseline)
- Server_FAVOR.py (FAVOR policy)
- Server_FLASHRL.py (FLASH-RL policy integrating RL agent)
- RL module
– RL/DQL.py (adapted Double DQN agent)
– RL/MLP_RL.py (neural network for Q-function)
- Model definitions
– models/ (CNN, ResNet for vision; LSTM/GRU for MobiAct)
- Persistence & reports
– models_saved/ (checkpointed local/global models)
– partition-reports/, figures/, prints/ (results, plots)

##### Key interactions and data-flows
1. Preparation
– Raw datasets → data_preprocessing → non-IID splits via data_division & data_manipulation → stored on disk.
2. FL round loop (serverFL)
a. Server loads global model.
b. Selection engine (FedAvg/FAVOR/FLASH-RL) chooses a subset of clients based on:
- Data characteristics
- Hardware profile (bandwidth, cores, frequency) from clients_info
- (FLASH-RL only) current RL policy state.
c. Server sends global model + selection instructions → selected clients.
d. Each Client.py loads its partition → local training (models/…) → returns model delta + metrics (accuracy, latency).
e. Server aggregates updates → new global model → logs performance, latency.
f. FLASH-RL: compute reward via reputation-based utility → feed (state, action, reward, next state) to RL agent (DQL.py) → update Q-network.
3. Reporting & storage
– Aggregation results → models_saved/ and figures/ → partition-reports/ & prints/ result_plot.py.

##### Architectural patterns and principles
- Modular layering: Data layer, Client layer, Server layer, RL-selection layer, Persistence layer.
- Pipeline for data preparation & distribution.
- Pluggable selection policies (Strategy pattern) in serverFL.
- RL agent integrated via an interface in Server_FLASHRL (Separation of concerns).

##### Final checklist
- Interactions: server↔clients; server↔RL agent; data pipeline→clients; storage sinks.
- Technology notes alongside modules (PyTorch, FedLab, NumPy).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        RawData["Raw Data"]:::dataclass
        Preprocess["Preprocessing (mobiAct)"]:::dataclass
        DivCIFAR["Division CIFAR-10"]:::dataclass
        DivMNIST["Division MNIST"]:::dataclass
        DivMobi["Division MobiAct"]:::dataclass
        DataDist["Data_distribution"]:::dataclass
        SubsetDS["Subset_dataset"]:::dataclass
    end

    RawData --> Preprocess
    Preprocess --> DivCIFAR & DivMNIST & DivMobi
    DivCIFAR --> DataDist
    DivMNIST --> DataDist
    DivMobi --> DataDist
    DataDist --> SubsetDS
    SubsetDS --> ClientPool

    %% Client Pool
    subgraph "Client Pool"
        direction TB
        Client["ClientFL/Client.py\n(local training)"]:::compute
        ProfilesC["clients_info/CIFAR10\n(hardware profiles)"]:::dataclass
        ProfilesM["clients_info/MobiAct\n(hardware profiles)"]:::dataclass
    end

    SubsetDS -->|"model + instructions"| Client
    ProfilesC -->|profiles| Selection
    ProfilesM -->|profiles| Selection

    %% FL Server
    subgraph "FL Server"
        direction TB
        Aggregation["Aggregation Engine"]:::compute
        subgraph "Selection Engine"
            direction TB
            FedP["FedAvg/FedProx"]:::compute
            Favor["FAVOR"]:::compute
            Flash["FLASH-RL"]:::compute
        end
    end

    Client -->|updates + metrics| Aggregation
    Aggregation -->|global model| Selection
    FedP --> Selection
    Favor --> Selection
    Selection -->|selected clients| Client

    %% RL Agent integration
    subgraph "RL Agent"
        direction TB
        DQL["DQL.py\n(Double DQN)"]:::rlclass
        MLP["MLP_RL.py\n(Q-network)"]:::rlclass
    end

    Flash -->|state,action,reward| DQL
    DQL -->|Q-updates| MLP
    MLP -->|policy| Flash

    %% Models
    subgraph "Model Definitions"
        direction TB
        CNN_CIFAR["CIFAR10\nCNN.py"]:::compute
        ResNet["CIFAR10\nResNet.py"]:::compute
        CNN_MNIST["MNIST\nCNN.py"]:::compute
        GRU["MobiAct\nGRU.py"]:::compute
        LSTM["MobiAct\nLSTM.py"]:::compute
    end

    Client -->|uses| CNN_CIFAR & ResNet & CNN_MNIST & GRU & LSTM

    %% Storage & Reports
    subgraph "Storage & Reports"
        direction TB
        MSS1["CNNmodel.pt\n(CIFAR10)"]:::dataclass
        MSS2["CNNmodel.pt\n(MNIST)"]:::dataclass
        MSS3["model_GRU.pt\n(MobiAct)"]:::dataclass
        FIG["Global_solution.pdf"]:::dataclass
        PR["partition-reports\n(README)"]:::dataclass
        RP["result_plot.py"]:::dataclass
    end

    Aggregation --> MSS1 & MSS2 & MSS3
    Aggregation --> FIG
    FIG --> PR
    RP --> PR

    %% Click Events
    click Preprocess "https://github.com/sofianebouaziz1/flash-rl/blob/main/data_preprocessing/mobiAct_preprocessing.py"
    click DivCIFAR "https://github.com/sofianebouaziz1/flash-rl/blob/main/data_division/CIFAR10/README.md"
    click DivMNIST "https://github.com/sofianebouaziz1/flash-rl/blob/main/data_division/MNIST/README.md"
    click DivMobi "https://github.com/sofianebouaziz1/flash-rl/blob/main/data_division/MobiAct/MobiAct_divisions.py"
    click DataDist "https://github.com/sofianebouaziz1/flash-rl/blob/main/data_manipulation/Data_distribution.py"
    click SubsetDS "https://github.com/sofianebouaziz1/flash-rl/blob/main/data_manipulation/Subset_dataset.py"
    click Client "https://github.com/sofianebouaziz1/flash-rl/blob/main/clientFL/Client.py"
    click ProfilesC "https://github.com/sofianebouaziz1/flash-rl/tree/main/clients_info/CIFAR10/"
    click ProfilesM "https://github.com/sofianebouaziz1/flash-rl/tree/main/clients_info/MobiAct/"
    click FedP "https://github.com/sofianebouaziz1/flash-rl/blob/main/serverFL/Server_FedProx.py"
    click Favor "https://github.com/sofianebouaziz1/flash-rl/blob/main/serverFL/Server_FAVOR.py"
    click Flash "https://github.com/sofianebouaziz1/flash-rl/blob/main/serverFL/Server_FLASHRL.py"
    click DQL "https://github.com/sofianebouaziz1/flash-rl/blob/main/RL/DQL.py"
    click MLP "https://github.com/sofianebouaziz1/flash-rl/blob/main/RL/MLP_RL.py"
    click CNN_CIFAR "https://github.com/sofianebouaziz1/flash-rl/blob/main/models/CIFAR10/CNN.py"
    click ResNet "https://github.com/sofianebouaziz1/flash-rl/blob/main/models/CIFAR10/ResNet.py"
    click CNN_MNIST "https://github.com/sofianebouaziz1/flash-rl/blob/main/models/MNIST/CNN.py"
    click GRU "https://github.com/sofianebouaziz1/flash-rl/blob/main/models/MobiAct/GRU.py"
    click LSTM "https://github.com/sofianebouaziz1/flash-rl/blob/main/models/MobiAct/LSTM.py"
    click MSS1 "https://github.com/sofianebouaziz1/flash-rl/blob/main/models_saved/CIFAR10/CNNmodel.pt"
    click MSS2 "https://github.com/sofianebouaziz1/flash-rl/blob/main/models_saved/MNIST/CNNmodel.pt"
    click MSS3 "https://github.com/sofianebouaziz1/flash-rl/blob/main/models_saved/MobiACT/model_GRU.pt"
    click FIG "https://github.com/sofianebouaziz1/flash-rl/blob/main/figures/Global_solution.pdf"
    click PR "https://github.com/sofianebouaziz1/flash-rl/blob/main/partition-reports/README.md"
    click RP "https://github.com/sofianebouaziz1/flash-rl/blob/main/prints/result_plot.py"

    %% Styles
    classDef dataclass fill:#cee4f9,stroke:#1f78b4,color:#0b3d91,stroke-width:1px;
    classDef compute fill:#d4f5d4,stroke:#28a428,color:#196619,stroke-width:1px;
    classDef rlclass fill:#ffe4b5,stroke:#ff8c00,color:#a45a00,stroke-width:1px;
```
