# veigargit/fl_serverpuma architecture

> Architecture diagram of the GitHub repository veigargit/fl_serverpuma, 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/veigargit/fl_serverpuma
- Repository: https://github.com/veigargit/fl_serverpuma

## Overview

FL_ServerPuma is a research simulator for federated training under constrained compute and network conditions. Its central workflow partitions datasets, starts a server and clients, exchanges model updates over training rounds, and evaluates the resulting models. Server-side adaptive pruning and client-side FedALA/LoRA/SoRA are distinct capabilities; LHDQ supports compressed model exchange. A SUMO-based V2V orchestrator provides an additional opportunistic-training environment, while result utilities support analysis. The README documents execution modes and features; sampled excerpts confirm selected call paths, so uncertain subsystem wiring is omitted.

Main entry points: [`src/system/client.py`](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/client.py) (Federated clients), [`src/system/server.py`](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/server.py) (Federated server), [`docker/generate_compose.py`](https://github.com/veigargit/fl_serverpuma/blob/main/docker/generate_compose.py) (Docker runtime), [`src/sumo_adapter/sumo_docker_orchestrator.py`](https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/sumo_docker_orchestrator.py) (SUMO orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_generators["Dataset generators"]
  node_partitions["Client partitions"]
end

subgraph group_federated["Federated runtime"]
  node_server["Federated server<br/>[server.py]"]
  node_clients["Federated clients<br/>[client.py]"]
  node_compression["LHDQ compression<br/>[lhdq.py]"]
  node_docker["Docker runtime"]
end

subgraph group_models["Model training"]
  node_cnn["CNN model<br/>[model.py]"]
  node_clipmain["CLIP training<br/>[main.py]"]
  node_cliptrainer["CLIP trainer<br/>[trainer.py]"]
  node_slmmain["SLM training<br/>[main.py]"]
  node_slmtrainer["SLM trainer<br/>[trainer.py]"]
  node_ala["FedALA<br/>[ALA.py]"]
  node_pruning["Adaptive pruning<br/>[prunning.py]"]
end

subgraph group_v2v["V2V simulation"]
  node_sumo["SUMO orchestrator"]
  node_traffic["SUMO traffic"]
  node_v2vcompose["V2V composition"]
end

subgraph group_analysis["Results analysis"]
  node_results["Experiment results"]
  node_resultutils["Result utilities<br/>[result_utils.py]"]
  node_plots["Result plots<br/>[plot_results.py]"]
  node_v2vplots["V2V plots"]
end

node_researcher(("Experimenter"))

node_researcher -->|"generates partitions"| node_generators
node_generators -->|"writes partitions"| node_partitions
node_researcher -->|"configures runs"| node_docker
node_docker -->|"starts server"| node_server
node_docker -->|"starts clients"| node_clients
node_clients -->|"loads local data"| node_partitions
node_server -->|"sends model and prune"| node_clients
node_clients -->|"returns updates"| node_server
node_server -->|"adapts pruning"| node_pruning
node_server -->|"encodes model state"| node_compression
node_clients -->|"decodes model state"| node_compression
node_clients -->|"trains model"| node_cnn
node_clients -.->|"applies local aggregation"| node_ala
node_clipmain -->|"runs epochs"| node_cliptrainer
node_slmmain -->|"runs epochs"| node_slmtrainer
node_researcher -->|"configures V2V run"| node_sumo
node_sumo -->|"controls simulation"| node_traffic
node_sumo -->|"starts containers"| node_v2vcompose
node_clients -->|"writes metrics"| node_results
node_resultutils -->|"reads results"| node_results
node_plots -->|"reads experiment data"| node_results
node_v2vplots -->|"reads V2V data"| node_results

click node_generators "https://github.com/veigargit/fl_serverpuma/tree/main/src/dataset"
click node_server "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/server.py"
click node_clients "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/client.py"
click node_compression "https://github.com/veigargit/fl_serverpuma/blob/main/src/utils/lhdq.py"
click node_cnn "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/model.py"
click node_clipmain "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_clip/main.py"
click node_cliptrainer "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_clip/trainer.py"
click node_slmmain "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_slm/main.py"
click node_slmtrainer "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_slm/trainer.py"
click node_ala "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/ALA.py"
click node_pruning "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/prunning.py"
click node_docker "https://github.com/veigargit/fl_serverpuma/blob/main/docker/generate_compose.py"
click node_sumo "https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/sumo_docker_orchestrator.py"
click node_v2vcompose "https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/generate_v2v_compose.py"
click node_resultutils "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/result_utils.py"
click node_plots "https://github.com/veigargit/fl_serverpuma/blob/main/src/system/plot/plot_results.py"
click node_v2vplots "https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/plot/plot_v2v_accuracy.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_generators,node_partitions toneBlue
class node_server,node_clients,node_compression,node_docker toneAmber
class node_cnn,node_clipmain,node_cliptrainer,node_slmmain,node_slmtrainer,node_ala,node_pruning toneMint
class node_sumo,node_traffic,node_v2vcompose toneRose
class node_results,node_resultutils,node_plots,node_v2vplots,node_researcher toneIndigo
```

## Components

### Data preparation

- [Dataset generators](https://github.com/veigargit/fl_serverpuma/tree/main/src/dataset): `src/dataset`
- **Client partitions**

### Federated runtime

- [Federated server](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/server.py): `src/system/server.py`
- [Federated clients](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/client.py): `src/system/client.py`
- [LHDQ compression](https://github.com/veigargit/fl_serverpuma/blob/main/src/utils/lhdq.py): `src/utils/lhdq.py`
- [Docker runtime](https://github.com/veigargit/fl_serverpuma/blob/main/docker/generate_compose.py): `docker/generate_compose.py`

### Model training

- [CNN model](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/model.py): `src/system/model.py`
- [CLIP training](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_clip/main.py): `src/system/lora_clip/main.py`
- [CLIP trainer](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_clip/trainer.py): `src/system/lora_clip/trainer.py`
- [SLM training](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_slm/main.py): `src/system/lora_slm/main.py`
- [SLM trainer](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/lora_slm/trainer.py): `src/system/lora_slm/trainer.py`
- [FedALA](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/ALA.py): `src/system/ALA.py`
- [Adaptive pruning](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/prunning.py): `src/system/prunning.py`

### V2V simulation

- [SUMO orchestrator](https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/sumo_docker_orchestrator.py): `src/sumo_adapter/sumo_docker_orchestrator.py`
- **SUMO traffic**
- [V2V composition](https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/generate_v2v_compose.py): `src/sumo_adapter/generate_v2v_compose.py`

### Results analysis

- **Experiment results**
- [Result utilities](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/result_utils.py): `src/system/result_utils.py`
- [Result plots](https://github.com/veigargit/fl_serverpuma/blob/main/src/system/plot/plot_results.py): `src/system/plot/plot_results.py`
- [V2V plots](https://github.com/veigargit/fl_serverpuma/blob/main/src/sumo_adapter/plot/plot_v2v_accuracy.py): `src/sumo_adapter/plot/plot_v2v_accuracy.py`

### Other components

- **Experimenter**

## Connections

- Experimenter → Dataset generators: generates partitions
- Dataset generators → Client partitions: writes partitions
- Experimenter → Docker runtime: configures runs
- Docker runtime → Federated server: starts server
- Docker runtime → Federated clients: starts clients
- Federated clients → Client partitions: loads local data
- Federated server → Federated clients: sends model and prune
- Federated clients → Federated server: returns updates
- Federated server → Adaptive pruning: adapts pruning
- Federated server → LHDQ compression: encodes model state
- Federated clients → LHDQ compression: decodes model state
- Federated clients → CNN model: trains model
- Federated clients → FedALA: applies local aggregation
- CLIP training → CLIP trainer: runs epochs
- SLM training → SLM trainer: runs epochs
- Experimenter → SUMO orchestrator: configures V2V run
- SUMO orchestrator → SUMO traffic: controls simulation
- SUMO orchestrator → V2V composition: starts containers
- Federated clients → Experiment results: writes metrics
- Result utilities → Experiment results: reads results
- Result plots → Experiment results: reads experiment data
- V2V plots → Experiment results: reads V2V data