# hewlettpackard/packetrusher architecture

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

- Interactive diagram: https://gitdiagram.com/hewlettpackard/packetrusher
- Repository: https://github.com/hewlettpackard/packetrusher

## Overview

##### Project type and purpose
- PacketRusher is a standalone, command-line performance-testing and validation tool for 5G Core Networks.
- It simulates both UE (user equipment) and gNodeB (5G base station) at scale (up to 10k UEs), exercising N1 (NAS), N2 (NGAP), and N3 (GTP-U) interfaces.
- It embeds a mock 5GC/AMF for integration testing and leverages C/C++ GTP-U kernel modules via cgo.

##### File structure
- cmd/packetrusher.go: CLI entry point.
- config/: configuration definitions (YAML + loader).
- internal/: core Go modules segmented by concern:
- common: shared auth, SUCI concealing/deconcealing, tools
- control_test_engine: orchestrator and simulators for gNB and UE (context, NAS, NGAP dispatchers, scenarios, triggers)
- work_load_model: traffic models (Poisson, Gaussian, Exponential)
- analytics & monitoring: metrics collection and reporting
- script & templates: scenario codegen and test-case scaffolding
- lib/: third-party or in-tree C libraries exposed via cgo:
- gtp5g: kernel module wrapper for high-speed GTP-U tunnels
- ngap: SCTP/NGAP message encoding/decoding
- util_3gpp: 3GPP data types and helpers
- docker/, dev/, scenarios/, test/: environment setups, sample scenarios, and automated tests.

##### README for additional insights
- Confirms simulation of multi-UE/gNB, stress testing on N1/N2/N3, SUCI schemes, handovers, PDU sessions, roaming.
- Describes reliance on a custom gtp5g kernel module and pure-Go NGAP/NAS stacks borrowed from free5gc.

##### Final checklist
- Internal packages as sub-components of their parent modules.
- External dependencies (free5gc libraries, kernel modules, real 5GC).
- Data-flow directions and annotate interface types.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Orchestrator"
        CLIEntry["cmd/packetrusher.go"]:::go
        Script["internal/script/script.go"]:::go
        Templates["internal/templates/"]:::go
        Orchestrator["Orchestrator"]:::go
    end

    subgraph "Config Loader"
        ConfigGo["config/config.go"]:::util
        ConfigYML["config/config.yml"]:::util
    end

    subgraph "Control Plane Engine"
        subgraph "gNodeB Simulator"
            GNB["gNodeB Simulator\n(gnb.go)"]:::go
        end
        subgraph "UE Simulator"
            UE["UE Simulator\n(ue.go)"]:::go
        end
    end

    subgraph "Workload Model"
        Workload["Workload Model"]:::util
    end

    subgraph "Monitoring & Analytics"
        Monitor["Monitoring\n(monitor.go)"]:::util
        Analytics["Analytics"]:::util
    end

    subgraph "Native C Libraries & Kernel Modules"
        GTP5G["GTP-U Kernel Module\n(lib/gtp5g/)"]:::ext
        NGAPLib["NGAP Library\n(lib/ngap/)"]:::ext
        Util3GPP["3GPP Types\n(lib/util_3gpp/)"]:::ext
    end

    Mock5GC["Mock 5GC/AMF"]:::ext
    External5GC["External 5GC"]:::ext

    CLIEntry --> Orchestrator
    Script --> Orchestrator
    Templates --> Orchestrator
    ConfigGo --> Orchestrator
    ConfigYML --> Orchestrator

    Orchestrator --> GNB
    Orchestrator --> UE

    Workload --> GNB
    Workload --> UE

    GNB -->|"N2 (SCTP/NGAP)"| Mock5GC
    GNB -->|"N2 (SCTP/NGAP)"| External5GC

    UE -->|"N1 (NAS)"| GNB
    UE -->|"N3 (GTP-U)"| GTP5G
    GNB -->|"N3 (GTP-U)"| GTP5G

    GNB --> Monitor
    UE --> Monitor
    Monitor --> Orchestrator

    click CLIEntry "https://github.com/hewlettpackard/packetrusher/blob/main/cmd/packetrusher.go"
    click Script "https://github.com/hewlettpackard/packetrusher/blob/main/internal/script/script.go"
    click Templates "https://github.com/hewlettpackard/packetrusher/tree/main/internal/templates/"
    click ConfigGo "https://github.com/hewlettpackard/packetrusher/blob/main/config/config.go"
    click ConfigYML "https://github.com/hewlettpackard/packetrusher/blob/main/config/config.yml"
    click GNB "https://github.com/hewlettpackard/packetrusher/tree/main/internal/control_test_engine/gnb/"
    click UE "https://github.com/hewlettpackard/packetrusher/tree/main/internal/control_test_engine/ue/"
    click Workload "https://github.com/hewlettpackard/packetrusher/tree/main/internal/work_load_model/"
    click Monitor "https://github.com/hewlettpackard/packetrusher/blob/main/internal/monitoring/monitor.go"
    click Analytics "https://github.com/hewlettpackard/packetrusher/tree/main/internal/analytics/"
    click GTP5G "https://github.com/hewlettpackard/packetrusher/tree/main/lib/gtp5g/"
    click NGAPLib "https://github.com/hewlettpackard/packetrusher/tree/main/lib/ngap/"
    click Util3GPP "https://github.com/hewlettpackard/packetrusher/tree/main/lib/util_3gpp/"
    click Mock5GC "https://github.com/hewlettpackard/packetrusher/tree/main/test/aio5gc/"

    classDef go fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef util fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef ext fill:#C8E6C9,stroke:#333,stroke-width:1px
```
