# labsaint/mud-hog_federated_learning architecture

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

- Interactive diagram: https://gitdiagram.com/labsaint/mud-hog_federated_learning
- Repository: https://github.com/labsaint/mud-hog_federated_learning

## Overview

##### Main Components
- Experiment Runner / Orchestrator: Identify the main script files (main.py, _main.py, run_hete_fashion.sh) which kick off the experiments.
- Clients: Represent the modules in clients.py and clients_attackers.py. These simulate the behavior of benign, malicious, and unreliable clients in the federated learning loop.
- Server/Aggregator: Include server.py as the central aggregation point that collects and processes client updates.
- Dataset & Task Modules: Under the “tasks” directory are several task-specific scripts (e.g., cifar.py, fashion_mnist.py, mnist.py, imdb.py, and imdb_bert.py) which set up the training tasks and datasets for the FL experiments.
- Utility Modules: The “utils” directory (with scripts like allocateGPU.py, backdoor_semantic_utils.py, backdoor_utils.py, blur_images.py, and other general utils) provides helper functions and additional experiment functionalities like backdoor triggering and GPU allocation.
- Data Loader: The dataloader.py module is responsible for preparing the data distributions for the clients (including IID, non-IID, etc.).
- Experiment Parser & Configuration: parser.py, along with the command-line options laid out in the README, shows how experiments are configured and parameters are passed throughout the simulation.

##### Relationships and Interactions
- Client-Server Communication: Represent the two-way communication between multiple Client modules and the Aggregator (server.py). Emphasize that clients update their local models and upload gradient updates (including potential malicious modifications) to the server.
- Task Execution: Show that various task modules (located in the “tasks” directory) define the experimental setup, data domain (e.g., MNIST, CIFAR, IMDB), and nature of the training, which feeds into the overall FL cycle.
- Utility Integration: Illustrate that utility functions (from the utils directory) are employed at several stages across the data preprocessing, client simulation (e.g., inducing noise, backdoor attacks), and even hardware resource allocation.

##### Architectural Patterns and Design Principles
- Extensibility: Since different tasks and attacks can be plugged in, showing “interfaces” or key connection points between components (like where attack parameters or aggregation rules are set up) is useful.

## Diagram (Mermaid)

```mermaid
graph TD
    Parser["Experiment Parser & Configuration (parser.py)"]:::configuration

    subgraph "Experiment Runner / Orchestrator"
        O1["Orchestrator (_main.py)"]:::orchestrator
        O2["Orchestrator (main.py)"]:::orchestrator
        O3["Orchestrator (run_hete_fashion.sh)"]:::orchestrator
    end

    D1["Data Loader (dataloader.py)"]:::data

    subgraph "Clients"
        C1["Benign Clients (clients.py)"]:::client
        C2["Attacker Clients (clients_attackers.py)"]:::client
        C_merge["Clients Aggregation"]:::client
    end

    S1["Server/Aggregator (server.py)"]:::server

    subgraph "Task Modules"
        T1["CIFAR Task (cifar.py)"]:::task
        T2["Fashion MNIST Task (fashion_mnist.py)"]:::task
        T3["MNIST Task (mnist.py)"]:::task
        T4["IMDB Task (imdb.py)"]:::task
        T5["IMDB BERT Task (imdb_bert.py)"]:::task
    end

    subgraph "Utility Modules"
        U1["GPU Allocation (allocateGPU.py)"]:::utility
        U2["Backdoor Semantic Utils (backdoor_semantic_utils.py)"]:::utility
        U3["Backdoor Utils (backdoor_utils.py)"]:::utility
        U4["Image Blurring (blur_images.py)"]:::utility
        U5["General Utils (utils.py)"]:::utility
    end

    Parser -->|"init"| O1
    O1 --> D1
    O2 --> D1
    O3 --> D1

    O3 -->|"setup_tasks"| T1
    T1 -->|"provide_task_info"| D1

    D1 -->|"data_partition"| C_merge
    C1 --> C_merge
    C2 --> C_merge
    C_merge -->|"upload_gradients"| S1
    S1 -->|"model_update"| C_merge

    O1 -->|"allocate_GPU"| U1
    C2 -->|"attack_processing"| U3
    C1 -->|"pre_process"| U4
    U2 --> S1
    U5 --> S1

    classDef configuration fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef data fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef client fill:#577590,stroke:#333,stroke-width:2px,color:#fff;
    classDef server fill:#f94144,stroke:#333,stroke-width:2px,color:#fff;
    classDef task fill:#277da1,stroke:#333,stroke-width:2px,color:#fff;
    classDef utility fill:#f3722c,stroke:#333,stroke-width:2px,color:#fff;

    click Parser "https://github.com/labsaint/mud-hog_federated_learning/blob/main/parser.py"
    click O1 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/_main.py"
    click O2 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/main.py"
    click O3 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/run_hete_fashion.sh"
    click D1 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/dataloader.py"
    click C1 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/clients.py"
    click C2 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/clients_attackers.py"
    click S1 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/server.py"
    click T1 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/tasks/cifar.py"
    click T2 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/tasks/fashion_mnist.py"
    click T3 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/tasks/mnist.py"
    click T4 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/tasks/imdb.py"
    click T5 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/tasks/imdb_bert.py"
    click U1 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/utils/allocateGPU.py"
    click U2 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/utils/backdoor_semantic_utils.py"
    click U3 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/utils/backdoor_utils.py"
    click U4 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/utils/blur_images.py"
    click U5 "https://github.com/labsaint/mud-hog_federated_learning/blob/main/utils/utils.py"
```
