# nextmn/upf architecture

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

- Interactive diagram: https://gitdiagram.com/nextmn/upf
- Repository: https://github.com/nextmn/upf

## Overview

##### Project type and purpose
- NextMN-UPF is a backend network service written in Go that implements a 5G User Plane Function (UPF) in user space.
- It speaks PFCP on the control-plane side (toward an SMF, e.g., Free5GC), and handles GTP-U encapsulated user-plane traffic via a tun interface and Linux iptables/iproute2.

##### File structure
- Top-level:
- main.go – entrypoint
- config/ – YAML files defining PFCP addresses, interface names, logging parameters
- bash-completion/ – CLI completion scripts for the “upf” binary
- internal/
· app/ – core modules: PFCP entity, GTP entity setup, UP handler, tun interface, utilities
· config/ – code to load/validate config
· constants/ – protocol constants
- Build & CI scripts: Makefile, GitHub workflows, .pre-commit, go.mod/sum.

##### README
- Confirms it’s an experimental user-space UPF with PFCP association/session operations, PDR/FAR processing.
- Dependencies: Go toolchain at build time; at runtime: iproute2, iptables, /dev/net/tun, NET_ADMIN capability.

##### Main components
a. Control-Plane Component
- PFCP Server (internal/app/pfcp-entity.go): listens for PFCP Association Setup, Session Establishment/Modification from SMF.
- PFCP Logger (internal/app/pfcp-logger.go): logs PFCP transactions.
b. Session Manager & Rule Processor
- UP Handler (internal/app/up-handler.go): applies PDRs/FARs/SDF filters in RAM.
- Utility modules: rule matching, statistics, constants.
c. Data-Plane Component
- GTP Tunnel Interface (internal/app/gtp-entity.go + tun.go): sets up a tun device, decapsulates/encapsulates GTP packets.
- Linux Network Stack: iptables/iproute2 rules to steer traffic to/from tun device.
d. Configuration & CLI
- Config Loader (internal/config/config.go): parses YAML files.
- Logger (internal/config/logger.go): structured logging setup.
- main.go: bootstraps config, logger, PFCP, tun, UP handler.

##### Relationships and interactions
- SMF (Free5GC) ⇄ PFCP Server: PFCP Association, Session Setup/Modify
- PFCP messages → Session Manager → updates internal rule tables
- User-plane packets from gNB arrive as GTP-U on physical NIC
- Tun module decapsulates → hands raw IP packets to Session Manager for rule lookup → forwards out via tun or back through GTP
- Linux kernel (iptables/iproute2) steers traffic into the tun interface; forward rules applied externally.

##### Architectural patterns & design principles
- Modular layering: clear separation between control-plane (PFCP), session/rule processing, and data-plane (GTP/tun).
- Single binary CLI/service; configuration-driven.
- In-RAM rule tables: fast lookup at the cost of persistence.
- Uses Go’s goroutines for concurrent PFCP session handling and dataplane packet loops.

##### Final recommendations
- Be detailed: annotate protocols (PFCP, GTP-U), ports (8805 PFCP UDP), interface names (e.g., “upf-tun0”).
- Initialization flow: config → logger → PFCP listen → tun setup → packet loops.
- Dynamic parts: rule installation, packet forwarding path.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        SMF["SMF (Free5GC)"]:::external
        Kernel["Linux Kernel Network Stack"]:::external
    end

    %% UPF Service Components
    subgraph "UPF Service" 
        direction TB
        ConfigLoader["Config Loader"]:::shared
        Logger["Logger"]:::shared
        PFCPServer["PFCP Server<br/>(PFCP UDP 8805)"]:::cp
        PFCPLogger["PFCP Logger"]:::cp
        SessionMgr["Session Manager<br/>(PDR/FAR Engine)"]:::session
        Utils["Utility Modules"]:::session
        GTPTun["GTP/TUN Interface"]:::dp
    end

    %% Initialization Flow
    ConfigLoader -->|loads YAML| Logger
    Logger -->|initializes logs| PFCPServer
    Logger -->|initializes logs| GTPTun
    Logger -->|initializes logs| SessionMgr

    %% Control Plane Flow
    SMF -->|PFCP Association/Session| PFCPServer
    PFCPServer -->|logs transactions| PFCPLogger
    PFCPServer -->|update rules| SessionMgr

    %% Session Manager & Utilities
    SessionMgr -->|uses| Utils

    %% Data Plane Flow
    Kernel -->|GTP-U packets| GTPTun
    GTPTun -->|decapsulate| SessionMgr
    SessionMgr -->|forward packets| GTPTun
    GTPTun -->|encapsulate + GTP-U| Kernel

    %% Click Events
    click PFCPServer "https://github.com/nextmn/upf/blob/master/internal/app/setup.go"
    click PFCPLogger "https://github.com/nextmn/upf/blob/master/internal/app/pfcp-logger.go"
    click SessionMgr "https://github.com/nextmn/upf/blob/master/internal/app/up-handler.go"
    click Utils "https://github.com/nextmn/upf/blob/master/internal/app/utils.go"
    click GTPTun "https://github.com/nextmn/upf/blob/master/internal/app/gtp-entity.go"
    click GTPTun "https://github.com/nextmn/upf/blob/master/internal/app/tun.go"
    click ConfigLoader "https://github.com/nextmn/upf/blob/master/internal/config/config.go"
    click Logger "https://github.com/nextmn/upf/blob/master/internal/config/logger.go"
    click ConfigLoader "https://github.com/nextmn/upf/blob/master/config/upf1.yaml"
    click ConfigLoader "https://github.com/nextmn/upf/blob/master/config/upf2.yaml"
    click SMF "https://github.com/nextmn/upf/tree/master/bash-completion/completions/upf"
    click main "https://github.com/nextmn/upf/blob/master/main.go"

    %% Styles
    classDef cp fill:#D0E8FF,stroke:#004080
    classDef session fill:#E8FFD0,stroke:#408000
    classDef dp fill:#D0FFF0,stroke:#008040
    classDef shared fill:#F0F0F0,stroke:#808080
    classDef external fill:#FFE0B2,stroke:#804000
```
