# farooqpersonal12/tara-fl architecture

> Architecture diagram of the GitHub repository farooqpersonal12/tara-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/farooqpersonal12/tara-fl
- Repository: https://github.com/farooqpersonal12/tara-fl

## Overview

TARA-FL is a federated-learning research system that trains an MNIST model across clients and adapts defenses to suspicious updates. Its round workflow prepares client data, performs local training, scores updates, derives client trust and round risk, aggregates updates, and evaluates the global model. The repository also includes configurable experiment runners, attack variants, and plots for analyzing results. Some modules are represented from their tree paths or explicit usage in sampled code; their internal behavior and any unsampled wiring are not inferred.

Main entry points: [`experiments/run_unified.py`](https://github.com/farooqpersonal12/tara-fl/blob/main/experiments/run_unified.py) (Experiment runner), [`main.py`](https://github.com/farooqpersonal12/tara-fl/blob/main/main.py) (Training entry), [`server/server.py`](https://github.com/farooqpersonal12/tara-fl/blob/main/server/server.py) (Federated server), [`clients/client.py`](https://github.com/farooqpersonal12/tara-fl/blob/main/clients/client.py) (Federated client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Federated workflow"]
  node_main["Training entry<br/>[main.py]"]
  node_server["Federated server<br/>[server.py]"]
  node_client["Federated client<br/>[client.py]"]
  node_labelattack["Label-flip attack<br/>[label_flip.py]"]
end

subgraph group_defenses["Trust and defense"]
  node_pid["PID detector<br/>[pid_detector.py]"]
  node_robustpid["Robust PID detector"]
  node_trust["Trust engine<br/>[trust_engine.py]"]
  node_history["Trust history<br/>[trust_history.py]"]
  node_risk["Round risk<br/>[round_risk.py]"]
  node_aggregator["Adaptive aggregation"]
end

subgraph group_experiments["Experiments and analysis"]
  node_gradientattack["Update attacks<br/>[gradient_poison.py]"]
  node_unified["Experiment runner<br/>[run_unified.py]"]
  node_fedavg["FedAvg baseline"]
  node_results["Experiment results"]
  node_plots["Result visualization<br/>[plots.py]"]
end

subgraph group_ml["Model and data"]
  node_dataset["MNIST partitioning<br/>[dataset.py]"]
  node_model["MNIST model<br/>[model.py]"]
end

node_user(("Researcher"))

node_user -->|"starts training"| node_main
node_user -->|"configures experiments"| node_unified
node_main -->|"loads and partitions"| node_dataset
node_main -->|"creates and queries"| node_server
node_main -->|"creates and trains"| node_client
node_main -->|"wraps client data"| node_labelattack
node_main -->|"scores updates"| node_pid
node_main -->|"calculates trust"| node_trust
node_main -->|"assesses round"| node_risk
node_main -->|"requests aggregation"| node_aggregator
node_main -->|"evaluates model"| node_server
node_client -->|"trains and updates"| node_model
node_server -->|"initializes and evaluates"| node_model
node_server -->|"delegates aggregation"| node_aggregator
node_trust -->|"reads and updates"| node_history
node_unified -->|"loads and partitions"| node_dataset
node_unified -->|"creates and trains"| node_client
node_unified -.->|"applies update attacks"| node_gradientattack
node_unified -->|"scores updates"| node_pid
node_unified -.->|"selects detector"| node_robustpid
node_unified -->|"calculates trust"| node_trust
node_unified -->|"assesses round"| node_risk
node_unified -->|"selects aggregation"| node_aggregator
node_unified -.->|"selects baseline"| node_fedavg
node_unified -->|"writes results"| node_results
node_fedavg -->|"writes results"| node_results
node_results -->|"reads results"| node_plots

click node_main "https://github.com/farooqpersonal12/tara-fl/blob/main/main.py"
click node_server "https://github.com/farooqpersonal12/tara-fl/blob/main/server/server.py"
click node_client "https://github.com/farooqpersonal12/tara-fl/blob/main/clients/client.py"
click node_dataset "https://github.com/farooqpersonal12/tara-fl/blob/main/data/dataset.py"
click node_model "https://github.com/farooqpersonal12/tara-fl/blob/main/model/model.py"
click node_labelattack "https://github.com/farooqpersonal12/tara-fl/blob/main/attacks/label_flip.py"
click node_gradientattack "https://github.com/farooqpersonal12/tara-fl/blob/main/attacks/gradient_poison.py"
click node_pid "https://github.com/farooqpersonal12/tara-fl/blob/main/detection/pid_detector.py"
click node_robustpid "https://github.com/farooqpersonal12/tara-fl/blob/main/detection/robust_pid_detector.py"
click node_trust "https://github.com/farooqpersonal12/tara-fl/blob/main/trustengine/trust_engine.py"
click node_history "https://github.com/farooqpersonal12/tara-fl/blob/main/trustengine/trust_history.py"
click node_risk "https://github.com/farooqpersonal12/tara-fl/blob/main/risk/round_risk.py"
click node_aggregator "https://github.com/farooqpersonal12/tara-fl/blob/main/aggregation/adaptive_aggregator.py"
click node_unified "https://github.com/farooqpersonal12/tara-fl/blob/main/experiments/run_unified.py"
click node_fedavg "https://github.com/farooqpersonal12/tara-fl/blob/main/experiments/run_baseline_fedavg.py"
click node_results "https://github.com/farooqpersonal12/tara-fl/tree/main/experiments/experiments"
click node_plots "https://github.com/farooqpersonal12/tara-fl/blob/main/visualization/plots.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_main,node_server,node_client,node_labelattack toneBlue
class node_pid,node_robustpid,node_trust,node_history,node_risk,node_aggregator toneAmber
class node_gradientattack,node_unified,node_fedavg,node_results,node_plots toneMint
class node_dataset,node_model toneRose
class node_user toneIndigo
```

## Components

### Federated workflow

- [Training entry](https://github.com/farooqpersonal12/tara-fl/blob/main/main.py): `main.py`
- [Federated server](https://github.com/farooqpersonal12/tara-fl/blob/main/server/server.py): `server/server.py`
- [Federated client](https://github.com/farooqpersonal12/tara-fl/blob/main/clients/client.py): `clients/client.py`
- [Label-flip attack](https://github.com/farooqpersonal12/tara-fl/blob/main/attacks/label_flip.py): `attacks/label_flip.py`

### Trust and defense

- [PID detector](https://github.com/farooqpersonal12/tara-fl/blob/main/detection/pid_detector.py): `detection/pid_detector.py`
- [Robust PID detector](https://github.com/farooqpersonal12/tara-fl/blob/main/detection/robust_pid_detector.py): `detection/robust_pid_detector.py`
- [Trust engine](https://github.com/farooqpersonal12/tara-fl/blob/main/trustengine/trust_engine.py): `trustengine/trust_engine.py`
- [Trust history](https://github.com/farooqpersonal12/tara-fl/blob/main/trustengine/trust_history.py): `trustengine/trust_history.py`
- [Round risk](https://github.com/farooqpersonal12/tara-fl/blob/main/risk/round_risk.py): `risk/round_risk.py`
- [Adaptive aggregation](https://github.com/farooqpersonal12/tara-fl/blob/main/aggregation/adaptive_aggregator.py): `aggregation/adaptive_aggregator.py`

### Experiments and analysis

- [Update attacks](https://github.com/farooqpersonal12/tara-fl/blob/main/attacks/gradient_poison.py): `attacks/gradient_poison.py`
- [Experiment runner](https://github.com/farooqpersonal12/tara-fl/blob/main/experiments/run_unified.py): `experiments/run_unified.py`
- [FedAvg baseline](https://github.com/farooqpersonal12/tara-fl/blob/main/experiments/run_baseline_fedavg.py): `experiments/run_baseline_fedavg.py`
- [Experiment results](https://github.com/farooqpersonal12/tara-fl/tree/main/experiments/experiments): `experiments/experiments`
- [Result visualization](https://github.com/farooqpersonal12/tara-fl/blob/main/visualization/plots.py): `visualization/plots.py`

### Model and data

- [MNIST partitioning](https://github.com/farooqpersonal12/tara-fl/blob/main/data/dataset.py): `data/dataset.py`
- [MNIST model](https://github.com/farooqpersonal12/tara-fl/blob/main/model/model.py): `model/model.py`

### Other components

- **Researcher**

## Connections

- Researcher → Training entry: starts training
- Researcher → Experiment runner: configures experiments
- Training entry → MNIST partitioning: loads and partitions
- Training entry → Federated server: creates and queries
- Training entry → Federated client: creates and trains
- Training entry → Label-flip attack: wraps client data
- Training entry → PID detector: scores updates
- Training entry → Trust engine: calculates trust
- Training entry → Round risk: assesses round
- Training entry → Adaptive aggregation: requests aggregation
- Training entry → Federated server: evaluates model
- Federated client → MNIST model: trains and updates
- Federated server → MNIST model: initializes and evaluates
- Federated server → Adaptive aggregation: delegates aggregation
- Trust engine → Trust history: reads and updates
- Experiment runner → MNIST partitioning: loads and partitions
- Experiment runner → Federated client: creates and trains
- Experiment runner → Update attacks: applies update attacks
- Experiment runner → PID detector: scores updates
- Experiment runner → Robust PID detector: selects detector
- Experiment runner → Trust engine: calculates trust
- Experiment runner → Round risk: assesses round
- Experiment runner → Adaptive aggregation: selects aggregation
- Experiment runner → FedAvg baseline: selects baseline
- Experiment runner → Experiment results: writes results
- FedAvg baseline → Experiment results: writes results
- Experiment results → Result visualization: reads results