# qianyufan8/medgemma-fl architecture

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

- Interactive diagram: https://gitdiagram.com/qianyufan8/medgemma-fl
- Repository: https://github.com/qianyufan8/medgemma-fl

## Overview

MedGemma-FL is a runnable NVIDIA FLARE research baseline for federated QLoRA fine-tuning of MedGemma on histopathology tissue classification; pediatric trial matching and Gemma Scope auditing are planned, not implemented. The main workflow downloads and shards image data, trains site-local adapters, aggregates them into a global adapter bank, then supports inference and separate accuracy evaluation. The graph reflects README capabilities and sampled source; unsampled wiring is omitted where uncertain.

Main entry points: [`client.py`](https://github.com/qianyufan8/medgemma-fl/blob/main/client.py) (Site training client), [`job.py`](https://github.com/qianyufan8/medgemma-fl/blob/main/job.py) (Federated job recipe), [`run_inference.py`](https://github.com/qianyufan8/medgemma-fl/blob/main/run_inference.py) (Inference runner), [`run_evaluation.py`](https://github.com/qianyufan8/medgemma-fl/blob/main/run_evaluation.py) (Accuracy evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_downloader["Dataset downloader<br/>[download_data.py]"]
  node_dataset[("Image datasets")]
  node_preparer["Site shard preparation<br/>[prepare_data.py]"]
  node_splits[("Site JSON splits")]
end

subgraph group_federated["Federated training"]
  node_recipe["Federated job recipe<br/>[job.py]"]
  node_client["Site training client<br/>[client.py]"]
  node_aggregator["LoRA aggregation"]
end

subgraph group_shared["Model and adapter"]
  node_servermodel["Global LoRA bank<br/>[model.py]"]
  node_modelhelpers["MedGemma model helpers<br/>[model.py]"]
  node_datahelpers["Prompt and label helpers<br/>[data_utils.py]"]
  node_lorahelpers["LoRA rank helpers<br/>[lora_utils.py]"]
end

subgraph group_validation["Inference and evaluation"]
  node_inference["Inference runner<br/>[run_inference.py]"]
  node_inferencehelpers["Inference utilities<br/>[inference_utils.py]"]
  node_evaluation["Accuracy evaluation<br/>[run_evaluation.py]"]
  node_predictions["Predictions and metrics"]
end

node_researcher(("Researcher"))
node_zenodo["Zenodo datasets"]
node_hf["Hugging Face"]
node_nvflare["NVFlare runtime"]

node_researcher -->|"starts download"| node_downloader
node_downloader -->|"downloads"| node_zenodo
node_downloader -->|"extracts archives"| node_dataset
node_researcher -->|"starts preparation"| node_preparer
node_preparer -->|"reads images"| node_dataset
node_preparer -->|"writes site splits"| node_splits
node_researcher -->|"starts job"| node_recipe
node_recipe -->|"configures and launches"| node_nvflare
node_recipe -->|"dispatches training"| node_client
node_recipe -->|"configures global model"| node_servermodel
node_recipe -->|"selects aggregator"| node_aggregator
node_client -->|"exchanges adapter updates"| node_nvflare
node_client -->|"loads site data"| node_splits
node_client -->|"loads trainable model"| node_modelhelpers
node_client -->|"formats examples"| node_datahelpers
node_client -->|"truncates global bank"| node_lorahelpers
node_nvflare -->|"submits client updates"| node_aggregator
node_aggregator -->|"aggregates adapter bank"| node_servermodel
node_researcher -->|"runs prediction"| node_inference
node_inference -->|"loads and predicts"| node_inferencehelpers
node_inference -->|"reads validation samples"| node_splits
node_inferencehelpers -->|"loads base model"| node_modelhelpers
node_inference -->|"prints predictions"| node_predictions
node_researcher -->|"runs evaluation"| node_evaluation
node_evaluation -->|"generates predictions"| node_inferencehelpers
node_evaluation -.->|"may load pretrained weights"| node_hf
node_evaluation -->|"reads evaluation images"| node_dataset
node_evaluation -->|"reports accuracy metrics"| node_predictions
node_inference -.->|"may load pretrained weights"| node_hf

click node_downloader "https://github.com/qianyufan8/medgemma-fl/blob/main/download_data.py"
click node_preparer "https://github.com/qianyufan8/medgemma-fl/blob/main/prepare_data.py"
click node_recipe "https://github.com/qianyufan8/medgemma-fl/blob/main/job.py"
click node_client "https://github.com/qianyufan8/medgemma-fl/blob/main/client.py"
click node_aggregator "https://github.com/qianyufan8/medgemma-fl/blob/main/custom_aggregators.py"
click node_servermodel "https://github.com/qianyufan8/medgemma-fl/blob/main/model.py"
click node_modelhelpers "https://github.com/qianyufan8/medgemma-fl/blob/main/model.py"
click node_datahelpers "https://github.com/qianyufan8/medgemma-fl/blob/main/data_utils.py"
click node_lorahelpers "https://github.com/qianyufan8/medgemma-fl/blob/main/lora_utils.py"
click node_inference "https://github.com/qianyufan8/medgemma-fl/blob/main/run_inference.py"
click node_inferencehelpers "https://github.com/qianyufan8/medgemma-fl/blob/main/inference_utils.py"
click node_evaluation "https://github.com/qianyufan8/medgemma-fl/blob/main/run_evaluation.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_downloader,node_dataset,node_preparer,node_splits toneBlue
class node_recipe,node_client,node_aggregator toneAmber
class node_servermodel,node_modelhelpers,node_datahelpers,node_lorahelpers toneMint
class node_inference,node_inferencehelpers,node_evaluation,node_predictions toneRose
class node_researcher,node_zenodo,node_hf,node_nvflare toneIndigo
```

## Components

### Data preparation

- [Dataset downloader](https://github.com/qianyufan8/medgemma-fl/blob/main/download_data.py): `download_data.py`
- **Image datasets**
- [Site shard preparation](https://github.com/qianyufan8/medgemma-fl/blob/main/prepare_data.py): `prepare_data.py`
- **Site JSON splits**

### Federated training

- [Federated job recipe](https://github.com/qianyufan8/medgemma-fl/blob/main/job.py): `job.py`
- [Site training client](https://github.com/qianyufan8/medgemma-fl/blob/main/client.py): `client.py`
- [LoRA aggregation](https://github.com/qianyufan8/medgemma-fl/blob/main/custom_aggregators.py): `custom_aggregators.py`

### Model and adapter

- [Global LoRA bank](https://github.com/qianyufan8/medgemma-fl/blob/main/model.py): `model.py`
- [MedGemma model helpers](https://github.com/qianyufan8/medgemma-fl/blob/main/model.py): `model.py`
- [Prompt and label helpers](https://github.com/qianyufan8/medgemma-fl/blob/main/data_utils.py): `data_utils.py`
- [LoRA rank helpers](https://github.com/qianyufan8/medgemma-fl/blob/main/lora_utils.py): `lora_utils.py`

### Inference and evaluation

- [Inference runner](https://github.com/qianyufan8/medgemma-fl/blob/main/run_inference.py): `run_inference.py`
- [Inference utilities](https://github.com/qianyufan8/medgemma-fl/blob/main/inference_utils.py): `inference_utils.py`
- [Accuracy evaluation](https://github.com/qianyufan8/medgemma-fl/blob/main/run_evaluation.py): `run_evaluation.py`
- **Predictions and metrics**

### Other components

- **Researcher**
- **Zenodo datasets**
- **Hugging Face**
- **NVFlare runtime**

## Connections

- Researcher → Dataset downloader: starts download
- Dataset downloader → Zenodo datasets: downloads
- Dataset downloader → Image datasets: extracts archives
- Researcher → Site shard preparation: starts preparation
- Site shard preparation → Image datasets: reads images
- Site shard preparation → Site JSON splits: writes site splits
- Researcher → Federated job recipe: starts job
- Federated job recipe → NVFlare runtime: configures and launches
- Federated job recipe → Site training client: dispatches training
- Federated job recipe → Global LoRA bank: configures global model
- Federated job recipe → LoRA aggregation: selects aggregator
- Site training client → NVFlare runtime: exchanges adapter updates
- Site training client → Site JSON splits: loads site data
- Site training client → MedGemma model helpers: loads trainable model
- Site training client → Prompt and label helpers: formats examples
- Site training client → LoRA rank helpers: truncates global bank
- NVFlare runtime → LoRA aggregation: submits client updates
- LoRA aggregation → Global LoRA bank: aggregates adapter bank
- Researcher → Inference runner: runs prediction
- Inference runner → Inference utilities: loads and predicts
- Inference runner → Site JSON splits: reads validation samples
- Inference utilities → MedGemma model helpers: loads base model
- Inference runner → Predictions and metrics: prints predictions
- Researcher → Accuracy evaluation: runs evaluation
- Accuracy evaluation → Inference utilities: generates predictions
- Accuracy evaluation → Hugging Face: may load pretrained weights
- Accuracy evaluation → Image datasets: reads evaluation images
- Accuracy evaluation → Predictions and metrics: reports accuracy metrics
- Inference runner → Hugging Face: may load pretrained weights