# ongwinkent/maverick architecture

> Architecture diagram of the GitHub repository ongwinkent/maverick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ongwinkent/maverick
- Repository: https://github.com/ongwinkent/maverick

## Overview

Maverick is a medical-imaging federated-learning and federated-unlearning research framework. Its training workflow loads MedMNIST data, partitions retain and unlearn examples across clients, performs local updates with federated aggregation, evaluates the global model, and can save it. A separate unlearning entry point loads a trained model, applies a selected method—including local Maverick sensitivity optimization or baseline methods—and evaluates retain accuracy, unlearn accuracy, and membership-inference risk. The graph follows shown calls and README capabilities; unsampled implementation details are not expanded.

Main entry points: [`fl_strategies/training.py`](https://github.com/ongwinkent/maverick/blob/main/fl_strategies/training.py) (Federated trainer), [`unlearn_strategies/unlearn_func.py`](https://github.com/ongwinkent/maverick/blob/main/unlearn_strategies/unlearn_func.py) (Unlearning workflow), [`fl_main.py`](https://github.com/ongwinkent/maverick/blob/main/fl_main.py) (FL entry point), [`unlearn_main.py`](https://github.com/ongwinkent/maverick/blob/main/unlearn_main.py) (Unlearning entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_train_entry["FL entry point<br/>[fl_main.py]"]
  node_train_config["Training options<br/>[train_config.py]"]
  node_unlearn_entry["Unlearning entry point<br/>[unlearn_main.py]"]
  node_unlearn_config["Unlearning options<br/>[unlearn_config.py]"]
end

subgraph group_federated["Federated training"]
  node_fl_orchestrator["Federated trainer<br/>[training.py]"]
  node_client_updates["Client updates and aggregation<br/>[utils.py]"]
end

subgraph group_unlearning["Unlearning"]
  node_unlearn_flow["Unlearning workflow<br/>[unlearn_func.py]"]
  node_unlearn_methods["Unlearning methods<br/>[strategies.py]"]
end

subgraph group_shared["Data, models and evaluation"]
  node_dataset["MedMNIST and partitions<br/>[dataset.py]"]
  node_model_factory["Model constructors<br/>[models.py]"]
  node_resnet["ResNet architectures<br/>[resnet.py]"]
  node_metrics["Evaluation and privacy metrics<br/>[metrics.py]"]
  node_runtime_utils["Runtime utilities<br/>[utils.py]"]
end

node_user(("Researcher"))
node_medmnist["MedMNIST"]

node_user -->|"starts training"| node_train_entry
node_train_entry -->|"reads options"| node_train_config
node_train_entry -->|"sets seed"| node_runtime_utils
node_train_entry -->|"starts trainer"| node_fl_orchestrator
node_fl_orchestrator -->|"loads and partitions"| node_dataset
node_dataset -->|"loads datasets"| node_medmnist
node_fl_orchestrator -->|"constructs model"| node_model_factory
node_model_factory -->|"builds ResNet"| node_resnet
node_fl_orchestrator -->|"selects and trains clients"| node_client_updates
node_fl_orchestrator -->|"evaluates global model"| node_metrics
node_fl_orchestrator -->|"configures device"| node_runtime_utils
node_user -->|"starts unlearning"| node_unlearn_entry
node_unlearn_entry -->|"reads options"| node_unlearn_config
node_unlearn_entry -->|"runs workflow"| node_unlearn_flow
node_unlearn_flow -->|"loads and partitions"| node_dataset
node_unlearn_flow -->|"constructs model"| node_model_factory
node_unlearn_flow -->|"dispatches method"| node_unlearn_methods
node_unlearn_methods -.->|"uses optimization helpers"| node_client_updates
node_unlearn_flow -->|"evaluates unlearned model"| node_metrics
node_unlearn_flow -->|"configures device"| node_runtime_utils

click node_train_entry "https://github.com/ongwinkent/maverick/blob/main/fl_main.py"
click node_train_config "https://github.com/ongwinkent/maverick/blob/main/configs/train_config.py"
click node_unlearn_entry "https://github.com/ongwinkent/maverick/blob/main/unlearn_main.py"
click node_unlearn_config "https://github.com/ongwinkent/maverick/blob/main/configs/unlearn_config.py"
click node_fl_orchestrator "https://github.com/ongwinkent/maverick/blob/main/fl_strategies/training.py"
click node_client_updates "https://github.com/ongwinkent/maverick/blob/main/fl_strategies/utils.py"
click node_unlearn_flow "https://github.com/ongwinkent/maverick/blob/main/unlearn_strategies/unlearn_func.py"
click node_unlearn_methods "https://github.com/ongwinkent/maverick/blob/main/unlearn_strategies/strategies.py"
click node_dataset "https://github.com/ongwinkent/maverick/blob/main/src/dataset.py"
click node_model_factory "https://github.com/ongwinkent/maverick/blob/main/model/models.py"
click node_resnet "https://github.com/ongwinkent/maverick/blob/main/model/resnet.py"
click node_metrics "https://github.com/ongwinkent/maverick/blob/main/src/metrics.py"
click node_runtime_utils "https://github.com/ongwinkent/maverick/blob/main/src/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_train_entry,node_train_config,node_unlearn_entry,node_unlearn_config toneBlue
class node_fl_orchestrator,node_client_updates toneAmber
class node_unlearn_flow,node_unlearn_methods toneMint
class node_dataset,node_model_factory,node_resnet,node_metrics,node_runtime_utils toneRose
class node_user,node_medmnist toneIndigo
```

## Components

### Entry and configuration

- [FL entry point](https://github.com/ongwinkent/maverick/blob/main/fl_main.py): `fl_main.py`
- [Training options](https://github.com/ongwinkent/maverick/blob/main/configs/train_config.py): `configs/train_config.py`
- [Unlearning entry point](https://github.com/ongwinkent/maverick/blob/main/unlearn_main.py): `unlearn_main.py`
- [Unlearning options](https://github.com/ongwinkent/maverick/blob/main/configs/unlearn_config.py): `configs/unlearn_config.py`

### Federated training

- [Federated trainer](https://github.com/ongwinkent/maverick/blob/main/fl_strategies/training.py): `fl_strategies/training.py`
- [Client updates and aggregation](https://github.com/ongwinkent/maverick/blob/main/fl_strategies/utils.py): `fl_strategies/utils.py`

### Unlearning

- [Unlearning workflow](https://github.com/ongwinkent/maverick/blob/main/unlearn_strategies/unlearn_func.py): `unlearn_strategies/unlearn_func.py`
- [Unlearning methods](https://github.com/ongwinkent/maverick/blob/main/unlearn_strategies/strategies.py): `unlearn_strategies/strategies.py`

### Data, models and evaluation

- [MedMNIST and partitions](https://github.com/ongwinkent/maverick/blob/main/src/dataset.py): `src/dataset.py`
- [Model constructors](https://github.com/ongwinkent/maverick/blob/main/model/models.py): `model/models.py`
- [ResNet architectures](https://github.com/ongwinkent/maverick/blob/main/model/resnet.py): `model/resnet.py`
- [Evaluation and privacy metrics](https://github.com/ongwinkent/maverick/blob/main/src/metrics.py): `src/metrics.py`
- [Runtime utilities](https://github.com/ongwinkent/maverick/blob/main/src/utils.py): `src/utils.py`

### Other components

- **Researcher**
- **MedMNIST**

## Connections

- Researcher → FL entry point: starts training (evidence: `fl_main.py`)
- FL entry point → Training options: reads options (evidence: `fl_main.py`)
- FL entry point → Runtime utilities: sets seed (evidence: `fl_main.py`)
- FL entry point → Federated trainer: starts trainer (evidence: `fl_main.py`)
- Federated trainer → MedMNIST and partitions: loads and partitions (evidence: `fl_strategies/training.py`)
- MedMNIST and partitions → MedMNIST: loads datasets (evidence: `src/dataset.py`)
- Federated trainer → Model constructors: constructs model (evidence: `fl_strategies/training.py`)
- Model constructors → ResNet architectures: builds ResNet (evidence: `model/models.py`)
- Federated trainer → Client updates and aggregation: selects and trains clients (evidence: `fl_strategies/training.py`)
- Federated trainer → Evaluation and privacy metrics: evaluates global model (evidence: `fl_strategies/training.py`)
- Federated trainer → Runtime utilities: configures device (evidence: `fl_strategies/training.py`)
- Researcher → Unlearning entry point: starts unlearning (evidence: `unlearn_main.py`)
- Unlearning entry point → Unlearning options: reads options (evidence: `unlearn_main.py`)
- Unlearning entry point → Unlearning workflow: runs workflow
- Unlearning workflow → MedMNIST and partitions: loads and partitions (evidence: `unlearn_strategies/unlearn_func.py`)
- Unlearning workflow → Model constructors: constructs model (evidence: `unlearn_strategies/unlearn_func.py`)
- Unlearning workflow → Unlearning methods: dispatches method (evidence: `unlearn_strategies/unlearn_func.py`)
- Unlearning methods → Client updates and aggregation: uses optimization helpers
- Unlearning workflow → Evaluation and privacy metrics: evaluates unlearned model (evidence: `unlearn_strategies/unlearn_func.py`)
- Unlearning workflow → Runtime utilities: configures device (evidence: `unlearn_strategies/unlearn_func.py`)
