# faresmalik/fesvibs architecture

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

- Interactive diagram: https://gitdiagram.com/faresmalik/fesvibs
- Repository: https://github.com/faresmalik/fesvibs

## Overview

##### Project type and purpose
- Type: Open-source research toolkit implementing federated split learning of a Vision Transformer (ViT) with block sampling.
- Purpose: Enable hospitals/clients to collaboratively train a ViT for medical image classification without sharing raw data, by splitting the model between client & server, sampling intermediate features, and federating server-side weights.

##### File structure
Top-level scripts:
- centralized.py – centralized (non-federated) end-to-end training/testing.
- local.py – purely local per-client training/testing.
- SLViT.py – vanilla split learning with ViT (with optional DP).
- FeSViBS.py – federated split learning with block sampling (with optional DP).
Core libraries:
- dataset.py – data loading & preprocessing for HAM10000, BloodMNIST, Fed-ISIC2019.
- models.py – defines ViT blocks, classification head, block sampling module.
- utils.py – training loops, logging, checkpointing, metrics.
Assets:
- Figures/method.PNG – high-level method illustration.
- requirements.txt, LICENSE, README.md

##### README for architecture clues
- Two main flows: Split-Learning (SLViT) and Federated Split-Learning (FeSViBS).
- Key components: client-side ViT block(s), server-side ViT block(s), block sampling & pseudo-token distillation, federated aggregation of server parameters.

##### Main components & interactions
a. Clients (N hospitals)
– Data Loader (dataset.py)
– Client-side ViT segment (initial_block…k)
– Local optimizer & backprop for client segment (utils.py)
– Transmits hidden activations and receives gradients / pseudo-tokens.
b. Server
– Server-side ViT segment (blocks k+1…end in models.py)
– Block-Sampling Module (sample patch tokens → pseudo class token)
– Classification Head → computes loss ← sends gradients back.
– Federated Aggregator (FedAvg) for server segment weights & sampler parameters
– Differential Privacy (optional) on gradients / weight updates
c. Data Stores & External Services
– On-disk datasets (HAM10000 folder, FLamby path)
– MedMNIST API (BloodMNIST)
d. Orchestrator Scripts
– FeSViBS.py coordinates per-round local split-training, block sampling, then federated aggregation.
– SLViT.py / centralized.py / local.py follow analogous flows without federation or splitting.

##### Architectural patterns & design principles
– Split Learning: partitioning a single neural network across clients & server.
– Federated Learning: aggregating server-side model parameters across clients.
– Modular design: clear separation of data I/O, model definition, training logic, and orchestration.
– Extensibility: support for DP, varying block split points, pluggable optimizers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients (N Hospitals)"
        direction TB
        DataLoader["Data Loader\ndataset.py"]:::client
        ClientBlocks["Client-side ViT Blocks\n1–k\n(models.py)"]:::client
        Optimizer["Local Optimizer & Backprop\n(utils.py)"]:::client
    end

    %% Server Layer
    subgraph "Server"
        direction TB
        ServerBlocks["Server-side ViT Blocks\nk+1–end\n(models.py)"]:::server
        BlockSampler["Block Sampling Module\n(models.py)"]:::server
        ClassHead["Classification Head\n(models.py)"]:::server
    end

    %% Federation Orchestrator
    subgraph "Federation Orchestrator" 
        direction TB
        FeSViBS["FeSViBS.py\n(Federated Split-Learning Orchestrator)"]:::orchestrator
        SLViT["SLViT.py\n(Split-Learning Orchestrator)"]:::orchestrator
        centralized["centralized.py\n(Centralized Training)"]:::orchestrator
        local["local.py\n(Local-only Training)"]:::orchestrator
    end

    %% Data Stores & External APIs
    subgraph "Data Stores & External APIs"
        direction TB
        HAM["HAM10000 Folder\n(on-disk)"]:::external
        MedAPI["MedMNIST API"]:::external
    end

    %% Flows
    HAM -->|provides images| DataLoader
    MedAPI -->|fetches data| DataLoader
    DataLoader -->|"data batch"| ClientBlocks
    ClientBlocks -->|"hidden activations"| ServerBlocks
    ServerBlocks -->|"activations"| BlockSampler
    BlockSampler -->|"sampled tokens"| ClassHead
    ClassHead -->|"loss & gradients"| ServerBlocks
    ClassHead -.->|∇loss| ClientBlocks
    ClientBlocks -.->|∇loss| Optimizer
    Optimizer -->|update client weights| ClientBlocks

    %% Federation Exchanges
    FeSViBS <-->|"FedAvg exchange"| ServerBlocks
    FeSViBS <-->|"FedAvg exchange"| BlockSampler

    %% Click Events
    click DataLoader "https://github.com/faresmalik/fesvibs/blob/main/dataset.py"
    click ClientBlocks "https://github.com/faresmalik/fesvibs/blob/main/models.py"
    click Optimizer "https://github.com/faresmalik/fesvibs/blob/main/utils.py"
    click ServerBlocks "https://github.com/faresmalik/fesvibs/blob/main/models.py"
    click BlockSampler "https://github.com/faresmalik/fesvibs/blob/main/models.py"
    click ClassHead "https://github.com/faresmalik/fesvibs/blob/main/models.py"
    click FeSViBS "https://github.com/faresmalik/fesvibs/blob/main/FeSViBS.py"
    click SLViT "https://github.com/faresmalik/fesvibs/blob/main/SLViT.py"
    click centralized "https://github.com/faresmalik/fesvibs/blob/main/centralized.py"
    click local "https://github.com/faresmalik/fesvibs/blob/main/local.py"
    click HAM "https://github.com/faresmalik/fesvibs/blob/main/Figures/method.PNG"

    %% Styles
    classDef client fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef server fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
