# yigitcemakbas/n3-accelerator architecture

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

- Interactive diagram: https://gitdiagram.com/yigitcemakbas/n3-accelerator
- Repository: https://github.com/yigitcemakbas/n3-accelerator

## Overview

This is an XDP-based 5G GTP-U router with a Go control plane. The principal workflow is: an administrator configures subscriber forwarding rules, the control plane writes them to pinned eBPF maps, and the attached kernel program handles uplink decapsulation or downlink encapsulation, NAT, rate limiting, quarantine, and redirect. The dashboard reads rule tables and verdict statistics. The README documents these capabilities; sampled source confirms map access, attachment, and selected packet-processing behavior, but does not expose every datapath branch.

Main entry points: [`gtp-router/ebpf/gtp_xdp.c`](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c) (XDP packet engine), [`gtp-router/control/maps/maps.go`](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go) (Map access), [`gtp-router/control/cmd`](https://github.com/yigitcemakbas/n3-accelerator/tree/main/gtp-router/control/cmd) (CLI commands), [`gtp-router/control/tui/dashboard.go`](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/tui/dashboard.go) (Terminal dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dataplane["Kernel dataplane"]
  node_xdp["XDP packet engine<br/>[gtp_xdp.c]"]
  node_decap["Uplink decap<br/>[gtp_xdp.c]"]
  node_encap["Downlink encap<br/>[gtp_xdp.c]"]
  node_nat["Static NAT<br/>[gtp_xdp.c]"]
  node_enforcement["Rate quarantine<br/>[gtp_xdp.c]"]
end

subgraph group_state["Pinned BPF state"]
  node_teid[("TEID rules<br/>[maps.go]")]
  node_ueip[("UE IP rules<br/>[maps.go]")]
  node_natmap[("NAT rules<br/>[maps.go]")]
  node_txport[("Redirect devmap<br/>[maps.go]")]
  node_statsmap[("Verdict counters<br/>[stats.go]")]
end

subgraph group_control["Control plane"]
  node_cli["CLI commands"]
  node_loader["XDP loader<br/>[loader.go]"]
  node_mapapi["Map access<br/>[maps.go]"]
end

subgraph group_monitor["Monitoring"]
  node_dashboard["Terminal dashboard<br/>[dashboard.go]"]
  node_statsread["Stats reader<br/>[stats.go]"]
end

node_admin(("Administrator"))
node_traffic(("GTP-U traffic"))
node_egress(("Network interfaces"))

node_admin -->|"configures"| node_cli
node_cli -->|"manages rules"| node_mapapi
node_mapapi -->|"writes rules"| node_teid
node_mapapi -->|"writes rules"| node_ueip
node_mapapi -->|"writes rules"| node_natmap
node_cli -->|"loads or unloads"| node_loader
node_loader -->|"attaches program"| node_xdp
node_traffic -->|"enters XDP"| node_xdp
node_xdp -->|"looks up TEID"| node_teid
node_xdp -->|"looks up UE IP"| node_ueip
node_xdp -->|"looks up NAT"| node_natmap
node_xdp -->|"updates counters"| node_statsmap
node_xdp -->|"redirects frames"| node_txport
node_txport -->|"redirects to"| node_egress
node_xdp -->|"decapsulates uplink"| node_decap
node_xdp -->|"encapsulates downlink"| node_encap
node_xdp -->|"rewrites addresses"| node_nat
node_xdp -->|"enforces policy"| node_enforcement
node_admin -->|"views and edits"| node_dashboard
node_dashboard -->|"reads rules"| node_mapapi
node_dashboard -->|"requests counters"| node_statsread
node_statsread -->|"reads counters"| node_statsmap

click node_xdp "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c"
click node_decap "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c"
click node_encap "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c"
click node_nat "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c"
click node_enforcement "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c"
click node_teid "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go"
click node_ueip "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go"
click node_natmap "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go"
click node_txport "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go"
click node_statsmap "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/stats/stats.go"
click node_cli "https://github.com/yigitcemakbas/n3-accelerator/tree/main/gtp-router/control/cmd"
click node_loader "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/loader/loader.go"
click node_mapapi "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go"
click node_dashboard "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/tui/dashboard.go"
click node_statsread "https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/stats/stats.go"

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_xdp,node_decap,node_encap,node_nat,node_enforcement toneBlue
class node_teid,node_ueip,node_natmap,node_txport,node_statsmap toneAmber
class node_cli,node_loader,node_mapapi toneMint
class node_dashboard,node_statsread toneRose
class node_admin,node_traffic,node_egress toneIndigo
```

## Components

### Kernel dataplane

- [XDP packet engine](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c): `gtp-router/ebpf/gtp_xdp.c`
- [Uplink decap](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c): `gtp-router/ebpf/gtp_xdp.c`
- [Downlink encap](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c): `gtp-router/ebpf/gtp_xdp.c`
- [Static NAT](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c): `gtp-router/ebpf/gtp_xdp.c`
- [Rate quarantine](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/ebpf/gtp_xdp.c): `gtp-router/ebpf/gtp_xdp.c`

### Pinned BPF state

- [TEID rules](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go): `gtp-router/control/maps/maps.go`
- [UE IP rules](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go): `gtp-router/control/maps/maps.go`
- [NAT rules](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go): `gtp-router/control/maps/maps.go`
- [Redirect devmap](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go): `gtp-router/control/maps/maps.go`
- [Verdict counters](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/stats/stats.go): `gtp-router/control/stats/stats.go`

### Control plane

- [CLI commands](https://github.com/yigitcemakbas/n3-accelerator/tree/main/gtp-router/control/cmd): `gtp-router/control/cmd`
- [XDP loader](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/loader/loader.go): `gtp-router/control/loader/loader.go`
- [Map access](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/maps/maps.go): `gtp-router/control/maps/maps.go`

### Monitoring

- [Terminal dashboard](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/tui/dashboard.go): `gtp-router/control/tui/dashboard.go`
- [Stats reader](https://github.com/yigitcemakbas/n3-accelerator/blob/main/gtp-router/control/stats/stats.go): `gtp-router/control/stats/stats.go`

### Other components

- **Administrator**
- **GTP-U traffic**
- **Network interfaces**

## Connections

- Administrator → CLI commands: configures
- CLI commands → Map access: manages rules
- Map access → TEID rules: writes rules
- Map access → UE IP rules: writes rules
- Map access → NAT rules: writes rules
- CLI commands → XDP loader: loads or unloads
- XDP loader → XDP packet engine: attaches program
- GTP-U traffic → XDP packet engine: enters XDP
- XDP packet engine → TEID rules: looks up TEID
- XDP packet engine → UE IP rules: looks up UE IP
- XDP packet engine → NAT rules: looks up NAT
- XDP packet engine → Verdict counters: updates counters
- XDP packet engine → Redirect devmap: redirects frames
- Redirect devmap → Network interfaces: redirects to
- XDP packet engine → Uplink decap: decapsulates uplink
- XDP packet engine → Downlink encap: encapsulates downlink
- XDP packet engine → Static NAT: rewrites addresses
- XDP packet engine → Rate quarantine: enforces policy
- Administrator → Terminal dashboard: views and edits
- Terminal dashboard → Map access: reads rules
- Terminal dashboard → Stats reader: requests counters
- Stats reader → Verdict counters: reads counters