# qaisermuhammad/fedsemgnn architecture

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

- Interactive diagram: https://gitdiagram.com/qaisermuhammad/fedsemgnn
- Repository: https://github.com/qaisermuhammad/fedsemgnn

## Overview

FedSemGNN is a research framework for semantic-aware, federated reinforcement-learning orchestration of 6G edge service placement. The main workflow starts at the CLI, runs a placement algorithm against a simulated workload, encodes topology and service semantics, chooses placements and evaluates them, then synchronizes federated models. Documented capabilities also include mobility, privacy, fault tolerance, extreme-scale operation, and 6G power modeling. The README documents these capabilities, but sampled excerpts do not show all their runtime call sites; uncertain wiring is therefore omitted.

Main entry points: [`src/algorithms/FedSemGNN.py`](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/algorithms/FedSemGNN.py) (FedSemGNN), [`main.py`](https://github.com/qaisermuhammad/fedsemgnn/blob/main/main.py) (CLI entry), [`experiments`](https://github.com/qaisermuhammad/fedsemgnn/tree/main/experiments) (Experiment runs), [`experiments/metrics_logger.py`](https://github.com/qaisermuhammad/fedsemgnn/blob/main/experiments/metrics_logger.py) (Metrics logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Simulation"]
  node_cli["CLI entry<br/>[main.py]"]
  node_simulator["EdgeSimPy"]
  node_workload["Service workload"]
end

subgraph group_placement["Placement Algorithms"]
  node_fedsemgnn["FedSemGNN<br/>[FedSemGNN.py]"]
  node_baselines["Baseline algorithms"]
end

subgraph group_learning["Learning and Federation"]
  node_ppo["PPO agent<br/>[PPO.py]"]
  node_gcn["Topology GCN<br/>[gcn_encoder.py]"]
  node_graph["Graph utilities<br/>[graph_utils.py]"]
  node_semantic["Semantic learning"]
  node_semantic_utils["Semantic helpers<br/>[semantic_utils.py]"]
  node_config["Framework configuration<br/>[config.py]"]
  node_extreme["Extreme-scale federation"]
end

subgraph group_operations["Network Operations"]
  node_mobility["Mobility tracking"]
  node_fault["Fault tolerance"]
  node_power["6G power model<br/>[edge_6g_power.py]"]
  node_energy["Hardware energy model"]
end

subgraph group_evaluation["Experiments and Metrics"]
  node_experiments["Experiment runs"]
  node_metrics["Metrics logging<br/>[metrics_logger.py]"]
  node_analysis["Result visualizations"]
end

node_operator(("Experiment operator"))

node_operator -->|"starts run"| node_cli
node_cli -->|"dispatches algorithm"| node_fedsemgnn
node_cli -->|"dispatches baseline"| node_baselines
node_simulator -->|"provides simulation"| node_fedsemgnn
node_workload -->|"defines workload"| node_simulator
node_fedsemgnn -->|"selects actions"| node_ppo
node_fedsemgnn -->|"encodes topology"| node_gcn
node_graph -->|"provides graph"| node_gcn
node_fedsemgnn -->|"updates semantics"| node_semantic
node_fedsemgnn -->|"uses embeddings"| node_semantic_utils
node_config -->|"configures"| node_fedsemgnn
node_fedsemgnn -.->|"scales federation"| node_extreme
node_simulator -.->|"tracks movement"| node_mobility
node_fedsemgnn -.->|"uses resilience logic"| node_fault
node_fedsemgnn -.->|"estimates power"| node_power
node_fedsemgnn -.->|"models energy"| node_energy
node_operator -->|"runs studies"| node_experiments
node_experiments -->|"launches runs"| node_cli
node_experiments -->|"records results"| node_metrics
node_metrics -->|"supplies results"| node_analysis

click node_cli "https://github.com/qaisermuhammad/fedsemgnn/blob/main/main.py"
click node_workload "https://github.com/qaisermuhammad/fedsemgnn/tree/main/workloads"
click node_fedsemgnn "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/algorithms/FedSemGNN.py"
click node_baselines "https://github.com/qaisermuhammad/fedsemgnn/tree/main/src/algorithms"
click node_ppo "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/algorithms/PPO.py"
click node_gcn "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/utils/gcn_encoder.py"
click node_graph "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/utils/graph_utils.py"
click node_semantic "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/online_semantic_learning.py"
click node_semantic_utils "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/utils/semantic_utils.py"
click node_config "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/config.py"
click node_extreme "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/extreme_scale_federated.py"
click node_mobility "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/mobility/mobility_tracker.py"
click node_fault "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/multi_cluster_fault_tolerance.py"
click node_power "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/power_model/edge_6g_power.py"
click node_energy "https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/hardware_energy_modeling.py"
click node_experiments "https://github.com/qaisermuhammad/fedsemgnn/tree/main/experiments"
click node_metrics "https://github.com/qaisermuhammad/fedsemgnn/blob/main/experiments/metrics_logger.py"
click node_analysis "https://github.com/qaisermuhammad/fedsemgnn/tree/main/visualizations/analysis_plots"

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_cli,node_simulator,node_workload toneBlue
class node_fedsemgnn,node_baselines toneAmber
class node_ppo,node_gcn,node_graph,node_semantic,node_semantic_utils,node_config,node_extreme toneMint
class node_mobility,node_fault,node_power,node_energy toneRose
class node_experiments,node_metrics,node_analysis,node_operator toneIndigo
```

## Components

### Entry and Simulation

- [CLI entry](https://github.com/qaisermuhammad/fedsemgnn/blob/main/main.py): `main.py`
- **EdgeSimPy**
- [Service workload](https://github.com/qaisermuhammad/fedsemgnn/tree/main/workloads): `workloads`

### Placement Algorithms

- [FedSemGNN](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/algorithms/FedSemGNN.py): `src/algorithms/FedSemGNN.py`
- [Baseline algorithms](https://github.com/qaisermuhammad/fedsemgnn/tree/main/src/algorithms): `src/algorithms`

### Learning and Federation

- [PPO agent](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/algorithms/PPO.py): `src/algorithms/PPO.py`
- [Topology GCN](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/utils/gcn_encoder.py): `src/utils/gcn_encoder.py`
- [Graph utilities](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/utils/graph_utils.py): `src/utils/graph_utils.py`
- [Semantic learning](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/online_semantic_learning.py): `src/core/online_semantic_learning.py`
- [Semantic helpers](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/utils/semantic_utils.py): `src/utils/semantic_utils.py`
- [Framework configuration](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/config.py): `src/core/config.py`
- [Extreme-scale federation](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/extreme_scale_federated.py): `src/core/extreme_scale_federated.py`

### Network Operations

- [Mobility tracking](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/mobility/mobility_tracker.py): `src/mobility/mobility_tracker.py`
- [Fault tolerance](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/multi_cluster_fault_tolerance.py): `src/core/multi_cluster_fault_tolerance.py`
- [6G power model](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/power_model/edge_6g_power.py): `src/power_model/edge_6g_power.py`
- [Hardware energy model](https://github.com/qaisermuhammad/fedsemgnn/blob/main/src/core/hardware_energy_modeling.py): `src/core/hardware_energy_modeling.py`

### Experiments and Metrics

- [Experiment runs](https://github.com/qaisermuhammad/fedsemgnn/tree/main/experiments): `experiments`
- [Metrics logging](https://github.com/qaisermuhammad/fedsemgnn/blob/main/experiments/metrics_logger.py): `experiments/metrics_logger.py`
- [Result visualizations](https://github.com/qaisermuhammad/fedsemgnn/tree/main/visualizations/analysis_plots): `visualizations/analysis_plots`

### Other components

- **Experiment operator**

## Connections

- Experiment operator → CLI entry: starts run
- CLI entry → FedSemGNN: dispatches algorithm
- CLI entry → Baseline algorithms: dispatches baseline
- EdgeSimPy → FedSemGNN: provides simulation
- Service workload → EdgeSimPy: defines workload
- FedSemGNN → PPO agent: selects actions
- FedSemGNN → Topology GCN: encodes topology
- Graph utilities → Topology GCN: provides graph
- FedSemGNN → Semantic learning: updates semantics
- FedSemGNN → Semantic helpers: uses embeddings
- Framework configuration → FedSemGNN: configures
- FedSemGNN → Extreme-scale federation: scales federation
- EdgeSimPy → Mobility tracking: tracks movement
- FedSemGNN → Fault tolerance: uses resilience logic
- FedSemGNN → 6G power model: estimates power
- FedSemGNN → Hardware energy model: models energy
- Experiment operator → Experiment runs: runs studies
- Experiment runs → CLI entry: launches runs
- Experiment runs → Metrics logging: records results
- Metrics logging → Result visualizations: supplies results