# giorgiomess/oran-xapp-project architecture

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

- Interactive diagram: https://gitdiagram.com/giorgiomess/oran-xapp-project
- Repository: https://github.com/giorgiomess/oran-xapp-project

## Overview

This repository is a proof-of-concept O-RAN PHY/MAC metrics xApp paired with a gNB emulator. The main workflow discovers gNBs through the RIC, subscribes for metrics, receives and parses indications, and appends cell-load and per-UE measurements to CSV; a separate visualization tool reads those files for plots and summaries. The emulator maintains a fixed UE fleet and generates measurements before replying over the custom protobuf/UDP service model. The README documents the RIC and transport topology; unsampled implementation details are not inferred.

Main entry points: [`ran_metrics_xapp.py`](https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py) (Metrics xApp), [`gnb_message_handlers.c`](https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c) (gNB Message Handler), [`visualize_ran_metrics.py`](https://github.com/giorgiomess/oran-xapp-project/blob/main/visualize_ran_metrics.py) (CSV Visualization), [`ran_messages.proto`](https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_messages.proto) (Custom RAN Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_emulator["gNB Emulator"]
  node_gnb["gNB Message Handler"]
  node_handler_api["Handler API"]
  node_gnb_state["UE and PRB State"]
  node_measurements["Sampled Measurements"]
end

subgraph group_collection["Metrics Collection"]
  node_schema["Custom RAN Schema<br/>[ran_messages.proto]"]
  node_xapp["Metrics xApp"]
end

subgraph group_outputs["CSV Outputs"]
  node_cell_csv[("Cell Load CSV")]
  node_ue_csv[("UE Metrics CSV")]
end

subgraph group_analytics["Visualization"]
  node_visualizer["CSV Visualization"]
  node_plots["Plots and Summary"]
end

node_ric["Near-RT RIC"]
node_udp["UDP Transport"]
node_analyst(("Analyst"))

node_handler_api -->|"declares entry point"| node_gnb
node_gnb -->|"uses state"| node_gnb_state
node_gnb -->|"builds reports"| node_measurements
node_measurements -->|"encodes messages"| node_schema
node_xapp -->|"serializes requests"| node_schema
node_gnb -->|"receives and replies"| node_udp
node_udp -->|"carries requests and reports"| node_xapp
node_xapp -->|"discovers and subscribes"| node_ric
node_ric -->|"delivers indications"| node_xapp
node_xapp -->|"appends cell load"| node_cell_csv
node_xapp -->|"appends UE metrics"| node_ue_csv
node_analyst -->|"runs analysis"| node_visualizer
node_cell_csv -->|"loads cell data"| node_visualizer
node_ue_csv -->|"loads UE data"| node_visualizer
node_visualizer -->|"generates figures"| node_plots

click node_gnb "https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c"
click node_handler_api "https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.h"
click node_gnb_state "https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c"
click node_measurements "https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c"
click node_schema "https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_messages.proto"
click node_xapp "https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py"
click node_cell_csv "https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py"
click node_ue_csv "https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py"
click node_visualizer "https://github.com/giorgiomess/oran-xapp-project/blob/main/visualize_ran_metrics.py"
click node_plots "https://github.com/giorgiomess/oran-xapp-project/blob/main/visualize_ran_metrics.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_gnb,node_handler_api,node_gnb_state,node_measurements toneBlue
class node_schema,node_xapp toneAmber
class node_cell_csv,node_ue_csv toneMint
class node_visualizer,node_plots toneRose
class node_ric,node_udp,node_analyst toneIndigo
```

## Components

### gNB Emulator

- [gNB Message Handler](https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c): `gnb_message_handlers.c`
- [Handler API](https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.h): `gnb_message_handlers.h`
- [UE and PRB State](https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c): `gnb_message_handlers.c`
- [Sampled Measurements](https://github.com/giorgiomess/oran-xapp-project/blob/main/gnb_message_handlers.c): `gnb_message_handlers.c`

### Metrics Collection

- [Custom RAN Schema](https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_messages.proto): `ran_messages.proto`
- [Metrics xApp](https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py): `ran_metrics_xapp.py`

### CSV Outputs

- [Cell Load CSV](https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py): `ran_metrics_xapp.py`
- [UE Metrics CSV](https://github.com/giorgiomess/oran-xapp-project/blob/main/ran_metrics_xapp.py): `ran_metrics_xapp.py`

### Visualization

- [CSV Visualization](https://github.com/giorgiomess/oran-xapp-project/blob/main/visualize_ran_metrics.py): `visualize_ran_metrics.py`
- [Plots and Summary](https://github.com/giorgiomess/oran-xapp-project/blob/main/visualize_ran_metrics.py): `visualize_ran_metrics.py`

### Other components

- **Near-RT RIC**
- **UDP Transport**
- **Analyst**

## Connections

- Handler API → gNB Message Handler: declares entry point (evidence: `gnb_message_handlers.h`)
- gNB Message Handler → UE and PRB State: uses state (evidence: `gnb_message_handlers.c`)
- gNB Message Handler → Sampled Measurements: builds reports (evidence: `gnb_message_handlers.c`)
- Sampled Measurements → Custom RAN Schema: encodes messages (evidence: `gnb_message_handlers.c`)
- Metrics xApp → Custom RAN Schema: serializes requests (evidence: `ran_metrics_xapp.py`)
- gNB Message Handler → UDP Transport: receives and replies (evidence: `README.md`)
- UDP Transport → Metrics xApp: carries requests and reports (evidence: `README.md`)
- Metrics xApp → Near-RT RIC: discovers and subscribes (evidence: `ran_metrics_xapp.py`)
- Near-RT RIC → Metrics xApp: delivers indications (evidence: `ran_metrics_xapp.py`)
- Metrics xApp → Cell Load CSV: appends cell load (evidence: `ran_metrics_xapp.py`)
- Metrics xApp → UE Metrics CSV: appends UE metrics (evidence: `ran_metrics_xapp.py`)
- Analyst → CSV Visualization: runs analysis (evidence: `visualize_ran_metrics.py`)
- Cell Load CSV → CSV Visualization: loads cell data (evidence: `visualize_ran_metrics.py`)
- UE Metrics CSV → CSV Visualization: loads UE data (evidence: `visualize_ran_metrics.py`)
- CSV Visualization → Plots and Summary: generates figures (evidence: `visualize_ran_metrics.py`)