# michele-segata/simu5g architecture

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

- Interactive diagram: https://gitdiagram.com/michele-segata/simu5g
- Repository: https://github.com/michele-segata/simu5g

## Overview

Simu5G is an OMNeT++/INET-based simulation library for LTE, NR, and MEC user-plane studies. The repo is organized more like a reusable protocol stack and scenario library than a single application: the core C++ modules live under `src/`, while `simulations/`, `emulation/`, `showcases/`, and `tutorials/` provide ready-made network topologies and experiments.

The main architectural boundary is the protocol stack. From top to bottom, user traffic enters application modules in `src/apps/` (VoIP, CBR, VoD, alerting, MEC-specific apps), then flows through packet-flow and bearer mapping in `src/stack/packetFlowManager/` and `src/stack/ip2nic/`, then through PDCP/RRC, RLC, MAC, PHY, and finally into the radio/channel layer in `src/world/radio/`. This stack is implemented as a mix of C++ classes and NED compound/simple modules, with packet definitions in `.msg` files.

The radio access network is split by generation and node type. LTE/NR base station and UE NICs are defined in `src/stack/` and `src/nodes/NR/`, with separate modules for eNodeB, gNodeB, UE, D2D-capable variants, carrier aggregation, dual connectivity, handover, and scheduling. A good diagram should show the stack as layered modules attached to node types rather than as one monolithic “network” block.

The physical and MAC layers are where most radio behavior is modeled. `src/stack/phy/` includes realistic and dummy channel models, feedback generation, and air-frame packet handling. `src/stack/mac/` includes HARQ buffers/processes, AMC, schedulers, allocation modules, conflict graph logic, and support for multiple numerologies and TDD/FDD. These subsystems feed each other tightly: PHY feedback influences AMC/scheduling, and MAC scheduling determines transport over PHY.

The medium and propagation model is centralized in `src/world/radio/` and `src/stack/phy/ChannelModel/`. `ChannelControl`/`LteChannelControl` manage who can hear whom and route transmissions through the modeled radio world, while the channel model computes path loss, fading, shadowing, and interference. This is the main infrastructure boundary between simulated nodes and the shared wireless environment.

Core network behavior is intentionally lightweight and user-plane focused. `src/corenetwork/gtp/` contains the PGW/UPF-side GTP user and serializers, while `src/corenetwork/trafficFlowFilter/` handles traffic flow classification. The README makes clear that control plane and EPS bearer modeling are not implemented; “connections” are used instead, so diagrams should not include full LTE/5G control-plane signaling.

Inter-cell coordination is modeled through X2 and related stack managers. `src/x2/` provides X2 application client/server roles and message serializers, while `src/stack/hand overManager/`, `src/stack/dualConnectivityManager/`, and `src/stack/compManager/` implement handover, dual connectivity, and CoMP coordination logic. These modules form a lateral control path between base stations rather than a vertical packet path.

MEC is a major subsystem with its own internal platform. Under `src/nodes/mec/` and `src/apps/mec/`, the repo defines a MEC orchestrator, virtualisation infrastructure manager, MEC platform, service registry, and services like RNI and location services. External or user apps communicate through HTTP-like messages, socket managers, and application descriptors, so a diagram should separate MEC host infrastructure from the simulated UE-side MEC apps.

There are multiple dedicated MEC application families. The code under `src/apps/mec/`, `src/apps/mecRequestResponseApp/`, and `src/apps/mec/RealTimeVideoStreamingApp/` maps to the scenario folders in `simulations/NR/mec/` and `emulation/mec/`. These scenarios show different deployment styles: single host, multi-host, multi-operator, request/response, RNIS tests, and external UE/MEC app execution.

Traffic generation and background load are explicit subsystems, not incidental test data. `src/stack/backgroundTrafficGenerator/` and `src/nodes/backgroundCell/` model additional cells and UE traffic generators, especially for NR/LTE background traffic experiments. The `*_bgTraffic` scenario folders and their `trafficGeneratorConfigs/` inputs show that background load is a first-class input to network performance studies.

Mobility is partly externalized. `src/mobility/trafficLightMobility/` supports vehicular/traffic-light mobility patterns, and the simulation trees under `simulations/LTE/cars/` and `simulations/NR/cars/` integrate with SUMO-style road network artifacts. This means vehicle movement is usually configured as an experiment input rather than hardcoded in the radio stack.

The repository’s executable content is almost entirely scenario-driven. `simulations/` contains the testbeds for LTE and NR features such as standalone, dual connectivity, carrier aggregation, D2D, X2, handover, MEC, and video streaming. Each scenario bundles NED topology files, `.ini` configs, demo XML, and sometimes external trace files or generator configs, so a diagram should show scenarios as composition layers over the reusable library.

`emulation/` mirrors some simulation features but integrates real external processes. The presence of `run.sh`, `setup.sh`, and `teardown.sh` in emulation examples indicates that these scenarios coordinate Simu5G with external clients/servers and host networking. This is an important boundary if you want to distinguish pure simulation from real-time emulation.

`tests/fingerprint/` provides regression protection for model behavior. The CSV fingerprint baselines and `fingerprinttest.py` show that the project validates simulation output statistically rather than through unit tests alone. In an architecture diagram, this is best represented as a verification layer around the scenario library, not part of the runtime network path.

Build and documentation are standard but materially relevant. The project uses a top-level `Makefile`, OMNeT++ project metadata, and Sphinx documentation under `doc/`, with CI workflows for fingerprint tests and doc deployment. The repo therefore has three practical layers: reusable simulation library in `src/`, scenario/evidence assets in `simulations/` and `emulation/`, and validation/documentation in `tests/` and `doc/`.

Main entry points: [`src/nodes`](https://github.com/michele-segata/simu5g/tree/master/src/nodes) (RAN nodes), [`simulations/NR`](https://github.com/michele-segata/simu5g/tree/master/simulations/NR) (NR sims), [`simulations/LTE`](https://github.com/michele-segata/simu5g/tree/master/simulations/LTE) (LTE sims), [`src/stack/packetFlowManager`](https://github.com/michele-segata/simu5g/tree/master/src/stack/packetFlowManager) (Flow map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_library["Reusable stack"]
  node_n_apps["Apps"]
  node_n_packetflow["Flow map<br/>bearer mapping"]
  node_n_pdcp_rrc["PDCP/RRC<br/>control & PDCP"]
  node_n_rlc["RLC<br/>reliability layer"]
  node_n_mac["MAC<br/>scheduling & HARQ"]
  node_n_phy["PHY<br/>radio access"]
  node_n_radio["Radio world<br/>shared medium"]
  node_n_nodes_ran["RAN nodes<br/>UE/eNB/gNB"]
  node_n_x2["X2<br/>inter-cell control"]
  node_n_coord["Coordination<br/>handover/DC/CoMP"]
  node_n_core["Core net<br/>user plane"]
  node_n_bgtraffic["Background load<br/>traffic generation"]
  node_n_mobility["Mobility"]
end

subgraph group_grp_mec["MEC platform"]
  node_n_mec_host["MEC host<br/>host platform"]
  node_n_mec_apps["MEC apps<br/>edge apps"]
end

subgraph group_grp_scenarios["Scenarios"]
  node_n_simu_lte["LTE sims<br/>scenario suite"]
  node_n_simu_nr["NR sims<br/>scenario suite"]
  node_n_showcases["Showcases<br/>example scenarios"]
end

subgraph group_grp_emulation["Emulation"]
  node_n_emu["Emulation<br/>external process demos"]
end

subgraph group_grp_validation["Validation"]
  node_n_fingerprint["Fingerprints<br/>regression baselines"]
  node_n_docs["Docs"]
end

node_n_apps -->|"injects traffic"| node_n_packetflow
node_n_packetflow -->|"maps bearers"| node_n_pdcp_rrc
node_n_pdcp_rrc -->|"hands down"| node_n_rlc
node_n_rlc -->|"segments"| node_n_mac
node_n_mac -->|"schedules"| node_n_phy
node_n_phy -->|"transmits"| node_n_radio
node_n_nodes_ran -->|"hosts"| node_n_apps
node_n_nodes_ran -->|"contains"| node_n_packetflow
node_n_nodes_ran -->|"contains"| node_n_pdcp_rrc
node_n_nodes_ran -->|"contains"| node_n_rlc
node_n_nodes_ran -->|"contains"| node_n_mac
node_n_nodes_ran -->|"contains"| node_n_phy
node_n_radio -->|"feeds channel"| node_n_phy
node_n_x2 -->|"supports"| node_n_coord
node_n_coord -->|"coordinates"| node_n_nodes_ran
node_n_core -->|"terminates user plane"| node_n_packetflow
node_n_bgtraffic -->|"loads"| node_n_simu_nr
node_n_bgtraffic -->|"loads"| node_n_simu_lte
node_n_mobility -->|"drives"| node_n_simu_lte
node_n_mobility -->|"drives"| node_n_simu_nr
node_n_mec_host -->|"hosts"| node_n_mec_apps
node_n_mec_apps -->|"uses HTTP/socket"| node_n_core
node_n_simu_lte -->|"assembles"| node_n_nodes_ran
node_n_simu_nr -->|"assembles"| node_n_nodes_ran
node_n_simu_nr -->|"assembles"| node_n_mec_host
node_n_showcases -.->|"documents"| node_n_simu_nr
node_n_emu -->|"integrates"| node_n_mec_apps
node_n_emu -->|"integrates"| node_n_core
node_n_fingerprint -.->|"validates"| node_n_simu_lte
node_n_fingerprint -.->|"validates"| node_n_simu_nr
node_n_docs -.->|"describes"| node_n_simu_lte
node_n_docs -.->|"describes"| node_n_simu_nr
node_n_docs -.->|"describes"| node_n_mec_host

click node_n_apps "https://github.com/michele-segata/simu5g/tree/master/src/apps"
click node_n_packetflow "https://github.com/michele-segata/simu5g/tree/master/src/stack/packetFlowManager"
click node_n_pdcp_rrc "https://github.com/michele-segata/simu5g/tree/master/src/stack/pdcp_rrc"
click node_n_rlc "https://github.com/michele-segata/simu5g/tree/master/src/stack/rlc"
click node_n_mac "https://github.com/michele-segata/simu5g/tree/master/src/stack/mac"
click node_n_phy "https://github.com/michele-segata/simu5g/tree/master/src/stack/phy"
click node_n_radio "https://github.com/michele-segata/simu5g/tree/master/src/world/radio"
click node_n_nodes_ran "https://github.com/michele-segata/simu5g/tree/master/src/nodes"
click node_n_x2 "https://github.com/michele-segata/simu5g/tree/master/src/x2"
click node_n_coord "https://github.com/michele-segata/simu5g/tree/master/src/stack/handoverManager"
click node_n_core "https://github.com/michele-segata/simu5g/tree/master/src/corenetwork"
click node_n_bgtraffic "https://github.com/michele-segata/simu5g/tree/master/src/stack/backgroundTrafficGenerator"
click node_n_mobility "https://github.com/michele-segata/simu5g/tree/master/src/mobility/trafficLightMobility"
click node_n_mec_host "https://github.com/michele-segata/simu5g/tree/master/src/nodes/mec"
click node_n_mec_apps "https://github.com/michele-segata/simu5g/tree/master/src/apps/mec"
click node_n_simu_lte "https://github.com/michele-segata/simu5g/tree/master/simulations/LTE"
click node_n_simu_nr "https://github.com/michele-segata/simu5g/tree/master/simulations/NR"
click node_n_showcases "https://github.com/michele-segata/simu5g/tree/master/showcases/NR/standalone"
click node_n_emu "https://github.com/michele-segata/simu5g/tree/master/emulation"
click node_n_fingerprint "https://github.com/michele-segata/simu5g/tree/master/tests/fingerprint"
click node_n_docs "https://github.com/michele-segata/simu5g/tree/master/doc/src"

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_n_apps,node_n_packetflow,node_n_pdcp_rrc,node_n_rlc,node_n_mac,node_n_phy,node_n_radio,node_n_nodes_ran,node_n_x2,node_n_coord,node_n_core,node_n_bgtraffic,node_n_mobility toneBlue
class node_n_mec_host,node_n_mec_apps toneAmber
class node_n_simu_lte,node_n_simu_nr,node_n_showcases toneMint
class node_n_emu toneRose
class node_n_fingerprint,node_n_docs toneIndigo
```

## Components

### Reusable stack

Core protocol stack and reusable node models under src/

- [Apps](https://github.com/michele-segata/simu5g/tree/master/src/apps): traffic apps · VoIP, CBR, VoD, alerting, burst, and MEC user apps · `src/apps`
- [Flow map](https://github.com/michele-segata/simu5g/tree/master/src/stack/packetFlowManager): bearer mapping · Packet flow management and IP-to-NIC mapping · `src/stack/packetFlowManager`
- [PDCP/RRC](https://github.com/michele-segata/simu5g/tree/master/src/stack/pdcp_rrc): control & PDCP · Connection state and PDCP/RRC entities for LTE and NR · `src/stack/pdcp_rrc`
- [RLC](https://github.com/michele-segata/simu5g/tree/master/src/stack/rlc): reliability layer · AM/UM/TM entities, queues, and RLC PDUs · `src/stack/rlc`
- [MAC](https://github.com/michele-segata/simu5g/tree/master/src/stack/mac): scheduling & HARQ · HARQ buffers, AMC, schedulers, allocators, and conflict logic · `src/stack/mac`
- [PHY](https://github.com/michele-segata/simu5g/tree/master/src/stack/phy): radio access · PHY layers, feedback, and channel models · `src/stack/phy`
- [Radio world](https://github.com/michele-segata/simu5g/tree/master/src/world/radio): shared medium · Channel control and simulated wireless environment · `src/world/radio`
- [RAN nodes](https://github.com/michele-segata/simu5g/tree/master/src/nodes): UE/eNB/gNB · LTE/NR node and NIC compound modules · `src/nodes`
- [X2](https://github.com/michele-segata/simu5g/tree/master/src/x2): inter-cell control · X2 client/server roles and serializers for base-station coordination · `src/x2`
- [Coordination](https://github.com/michele-segata/simu5g/tree/master/src/stack/handoverManager): handover/DC/CoMP · Handover, dual connectivity, and CoMP managers · `src/stack/handoverManager`
- [Core net](https://github.com/michele-segata/simu5g/tree/master/src/corenetwork): user plane · GTP user plane and traffic flow filtering · `src/corenetwork`
- [Background load](https://github.com/michele-segata/simu5g/tree/master/src/stack/backgroundTrafficGenerator): traffic generation · Background traffic generators and background cells · `src/stack/backgroundTrafficGenerator`
- [Mobility](https://github.com/michele-segata/simu5g/tree/master/src/mobility/trafficLightMobility): vehicular mobility · Traffic-light mobility support · `src/mobility/trafficLightMobility`

### MEC platform

MEC host, orchestrator, platform, and MEC apps

- [MEC host](https://github.com/michele-segata/simu5g/tree/master/src/nodes/mec): host platform · MEC host, platform, registry, orchestrator, and virtualization management · `src/nodes/mec`
- [MEC apps](https://github.com/michele-segata/simu5g/tree/master/src/apps/mec): edge apps · Device-side and MEC-side application families · `src/apps/mec`

### Scenarios

Simulation and showcase configurations built from the reusable library

- [LTE sims](https://github.com/michele-segata/simu5g/tree/master/simulations/LTE): scenario suite · LTE demonstrations, handover, X2, D2D, cars, and tutorials · `simulations/LTE`
- [NR sims](https://github.com/michele-segata/simu5g/tree/master/simulations/NR): scenario suite · NR standalone, dual connectivity, D2D, MEC, cars, background traffic, and video streaming · `simulations/NR`
- [Showcases](https://github.com/michele-segata/simu5g/tree/master/showcases/NR/standalone): example scenarios · Curated showcase configurations · `showcases/NR/standalone`

### Emulation

External-process integration examples

- [Emulation](https://github.com/michele-segata/simu5g/tree/master/emulation): external process demos · Real-process integration scenarios for ext client/server and MEC apps · `emulation`

### Validation

Regression tests and documentation

- [Fingerprints](https://github.com/michele-segata/simu5g/tree/master/tests/fingerprint): regression baselines · Scenario output baselines and fingerprint test runner · `tests/fingerprint`
- [Docs](https://github.com/michele-segata/simu5g/tree/master/doc/src): sphinx docs · Sphinx documentation and guides · `doc/src`

## Connections

- Apps → Flow map: injects traffic · Applications hand packets into the stack
- Flow map → PDCP/RRC: maps bearers · Flow and bearer mapping into radio bearers
- PDCP/RRC → RLC: hands down · PDCP/RRC data continues into RLC
- RLC → MAC: segments · RLC feeds MAC scheduling and transport
- MAC → PHY: schedules · MAC controls transmission over PHY
- PHY → Radio world: transmits · PHY uses the shared radio world and channel control
- RAN nodes → Apps: hosts · UE and base-station nodes embed application endpoints
- RAN nodes → Flow map: contains · Node NICs include packet-flow integration
- RAN nodes → PDCP/RRC: contains · Node NICs include PDCP/RRC layers
- RAN nodes → RLC: contains · Node NICs include RLC entities
- RAN nodes → MAC: contains · Node NICs include MAC layers
- RAN nodes → PHY: contains · Node NICs include PHY layers
- Radio world → PHY: feeds channel · Medium and channel control serve the PHY models
- X2 → Coordination: supports · X2 signaling carries inter-cell coordination
- Coordination → RAN nodes: coordinates · Handover, dual connectivity, and CoMP operate between base stations
- Core net → Flow map: terminates user plane · Core-network user-plane handling connects to bearer mapping
- Background load → NR sims: loads · Background traffic is configured by NR scenarios
- Background load → LTE sims: loads · Background traffic is also used by LTE experiments
- Mobility → LTE sims: drives · Vehicular mobility is configured by LTE car scenarios
- Mobility → NR sims: drives · Vehicular mobility is configured by NR car scenarios
- MEC host → MEC apps: hosts · MEC platform hosts and serves MEC applications
- MEC apps → Core net: uses HTTP/socket · MEC applications communicate through user-plane style messaging
- LTE sims → RAN nodes: assembles · LTE scenarios compose reusable nodes and stack modules
- NR sims → RAN nodes: assembles · NR scenarios compose reusable nodes and stack modules
- NR sims → MEC host: assembles · NR MEC scenarios add MEC infrastructure and apps
- Showcases → NR sims: documents · Showcases provide curated NR example compositions
- Emulation → MEC apps: integrates · Emulation examples couple Simu5G with external MEC apps
- Emulation → Core net: integrates · Emulation examples couple Simu5G with external client/server processes
- Fingerprints → LTE sims: validates · Fingerprint baselines cover LTE scenarios
- Fingerprints → NR sims: validates · Fingerprint baselines cover NR scenarios
- Docs → LTE sims: describes · Documentation covers LTE scenarios and usage
- Docs → NR sims: describes · Documentation covers NR scenarios and usage
- Docs → MEC host: describes · Documentation covers MEC architecture and usage
