# layer6ai-labs/proxyfl architecture

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

- Interactive diagram: https://gitdiagram.com/layer6ai-labs/proxyfl
- Repository: https://github.com/layer6ai-labs/proxyfl

## Overview

##### Main Components
- Experiment Orchestrator: Represented by the main experiment scripts (run_exp.py and run_exp.sh) that drive the workflow.
- Data Management: A shell script (download_data.sh) is responsible for fetching the necessary datasets.
- Client (Local Training) Process: The client.py file likely initializes or interacts with decentralized client processes, which participate in the federated learning setup.
- Model Definition: The model.py file contains the neural network architecture used in the training.
- Training Module: The trainer.py script likely encapsulates the training routines, including local updates and proxy model sharing.
- Privacy Verification: The privacy_checker.py module integrates privacy techniques (potentially by using opacus) to ensure that differentially private constraints are met.
- Utility Functions: The utils.py file provides supportive functions which might be used across various components (data pre-processing, logging, etc.).
- Visualization: The plot.py module is used to generate visualizations of training results or performance metrics.

##### Detail Relationships and Interactions
- Data Flow: Begin with the data acquisition (download_data.sh) feeding data into the experiment scripts. Data is then preprocessed and passed along to the client modules.
- Client-Server (or Peer-to-Peer) Relationships: In decentralized federated learning, every client (initialized in client.py) carries out local model training (using trainer.py and model.py), and then shares a “proxy” version of its model with other peers.
- Privacy Integration: As models are shared, privacy_checker.py provides validations that the shared models conform to privacy standards.

##### Architectural Patterns and Technologies
- Decentralized Federated Learning: The system is organized in a peer-to-peer or decentralized fashion where every client participates in local training and then shares a proxy model.
- Modularity: The project’s separation into distinct scripts for training, client handling, privacy checking, and visualization shows a modular design.
- Use of Modern ML Libraries: PyTorch for model training, opacus for privacy, and mpi4py for communication are key technologies that underpin the system.
- Experiment-Driven: The presence of shell scripts to run experiments and download data emphasizes a research and experimental usage pattern.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Management Layer
    dl["download_data.sh"]:::dataManagement

    %% Experiment Orchestration Layer
    subgraph "Experiment Orchestration"
        exp1["run_exp.py"]:::orchestrator
        exp2["run_exp.sh"]:::orchestrator
    end

    %% Decentralized Client Process Layer
    subgraph "Decentralized Client Process"
        cli["client.py"]:::client
        mod["model.py"]:::client
        trn["trainer.py"]:::client
        priv["privacy_checker.py"]:::client
        util["utils.py"]:::client
    end

    %% Visualization and External Components
    viz["plot.py"]:::visualization
    mpi["MPI Communication Layer"]:::mpiLayer
    pt["PyTorch"]:::external
    opc["opacus"]:::external

    %% Data Flow Connections
    dl -->|"ingests_data"| exp1
    dl -->|"ingests_data"| exp2

    exp1 -->|"triggers_client"| cli
    exp2 -->|"triggers_client"| cli

    cli -->|"initiates_training"| trn
    trn -->|"builds_model"| mod
    trn -->|"verifies_model"| priv
    cli -->|"utilizes"| util

    %% External Library Integrations
    trn -->|"uses"| pt
    priv -->|"applies"| opc

    %% MPI Communication Connection
    cli -->|"communicates"| mpi
    mpi -->|"broadcasts_to"| cli

    %% Reporting Results
    cli -->|"reports_results"| viz


    %% Click Events
    click dl "https://github.com/layer6ai-labs/proxyfl/blob/main/download_data.sh"
    click exp1 "https://github.com/layer6ai-labs/proxyfl/blob/main/run_exp.py"
    click exp2 "https://github.com/layer6ai-labs/proxyfl/blob/main/run_exp.sh"
    click cli "https://github.com/layer6ai-labs/proxyfl/blob/main/client.py"
    click mod "https://github.com/layer6ai-labs/proxyfl/blob/main/model.py"
    click trn "https://github.com/layer6ai-labs/proxyfl/blob/main/trainer.py"
    click priv "https://github.com/layer6ai-labs/proxyfl/blob/main/privacy_checker.py"
    click util "https://github.com/layer6ai-labs/proxyfl/blob/main/utils.py"
    click viz "https://github.com/layer6ai-labs/proxyfl/blob/main/plot.py"

    %% Styles
    classDef orchestrator fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef dataManagement fill:#F0F4C3,stroke:#9E9D24,stroke-width:2px;
    classDef client fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef visualization fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef mpiLayer fill:#D7CCC8,stroke:#5D4037,stroke-width:2px;
    classDef external fill:#FFE082,stroke:#FF6F00,stroke-width:2px;
```
