# tokyoxpa3/5g-proxy-pro architecture

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

- Interactive diagram: https://gitdiagram.com/tokyoxpa3/5g-proxy-pro
- Repository: https://github.com/tokyoxpa3/5g-proxy-pro

## Overview

5G Proxy Pro is an Android app that shares the phone’s cellular connection through a LAN-only SOCKS5 proxy. The main workflow runs from user controls in the activity to the foreground service, which requests and maintains cellular connectivity and starts the native proxy; client traffic then crosses JNI to sockets bound to that network. The README also documents TCP, UDP, UDP-in-TCP, optional authentication, health recovery, and self-test/diagnostics. Some subsystem links are documented rather than visible in sampled implementation excerpts.

Main entry points: [`app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt) (Proxy service), [`app/src/main/cpp/simple-socks5.c`](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/simple-socks5.c) (SOCKS5 engine), [`app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt) (Control UI), [`app/src/main/cpp/jni_bridge.c`](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/jni_bridge.c) (JNI bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_activity["Control UI<br/>[DebugActivity.kt]"]
  node_service["Proxy service"]
  node_permissions["Power permissions"]
end

subgraph group_network["Cellular networking"]
  node_cellular["Cellular manager"]
  node_health["Health classifier"]
  node_hotspot["LAN address discovery<br/>[HotspotManager.kt]"]
  node_publicip["Public IP check<br/>[PublicIPChecker.kt]"]
  node_dns["DNS cache<br/>[DnsCache.kt]"]
  node_happy["Address racing<br/>[HappyEyeballs.kt]"]
  node_ipliteral["IP literal check<br/>[IpLiteral.kt]"]
end

subgraph group_bridge["JNI and native proxy"]
  node_nativeapi["Native API<br/>[NativeEngine.kt]"]
  node_jni["JNI bridge<br/>[jni_bridge.c]"]
  node_proxy["SOCKS5 engine<br/>[simple-socks5.c]"]
  node_protocol["Protocol codec<br/>[socks5_protocol.c]"]
  node_forward["TCP forwarding<br/>[conn_forward.c]"]
  node_state["Connection state<br/>[conn_state.c]"]
  node_udp["UDP relay<br/>[udp_conn.c]"]
  node_udpdns["UDP DNS support<br/>[udp_dns.c]"]
  node_purge["Ghost cleanup<br/>[ghost_purge.c]"]
end

subgraph group_diagnostics["Testing and diagnostics"]
  node_selftest["Proxy self-test<br/>[SelfTest.kt]"]
  node_clientprotocol["Test protocol"]
end

node_user(("Operator"))
node_internet(("Internet targets"))

node_user -->|"controls"| node_activity
node_activity -->|"starts and stops"| node_service
node_activity -->|"runs"| node_selftest
node_activity -->|"guides"| node_permissions
node_service -->|"requests network"| node_cellular
node_service -->|"classifies health"| node_health
node_service -->|"starts engine"| node_nativeapi
node_service -->|"discovers LAN"| node_hotspot
node_activity -->|"checks address"| node_publicip
node_service -->|"uses cache"| node_dns
node_service -->|"orders addresses"| node_happy
node_service -->|"checks host"| node_ipliteral
node_nativeapi -->|"calls native"| node_jni
node_jni -->|"calls callbacks"| node_nativeapi
node_jni -->|"dispatches"| node_proxy
node_proxy -->|"relays traffic"| node_internet
node_proxy -->|"uses codec"| node_protocol
node_proxy -->|"uses forwarding"| node_forward
node_proxy -->|"uses state"| node_state
node_proxy -->|"starts relay"| node_udp
node_proxy -->|"uses DNS support"| node_udpdns
node_proxy -->|"uses cleanup"| node_purge
node_selftest -->|"encodes requests"| node_clientprotocol
node_selftest -->|"tests proxy path"| node_service

click node_activity "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt"
click node_service "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt"
click node_permissions "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/PowerPermissionHelper.kt"
click node_cellular "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/CellularNetworkManager.kt"
click node_health "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/NetworkHealthClassifier.kt"
click node_hotspot "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/HotspotManager.kt"
click node_publicip "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/PublicIPChecker.kt"
click node_dns "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/DnsCache.kt"
click node_happy "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/HappyEyeballs.kt"
click node_ipliteral "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/IpLiteral.kt"
click node_nativeapi "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/NativeEngine.kt"
click node_jni "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/jni_bridge.c"
click node_proxy "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/simple-socks5.c"
click node_protocol "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/socks5_protocol.c"
click node_forward "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/conn_forward.c"
click node_state "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/conn_state.c"
click node_udp "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/udp_conn.c"
click node_udpdns "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/udp_dns.c"
click node_purge "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/ghost_purge.c"
click node_selftest "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/SelfTest.kt"
click node_clientprotocol "https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ClientProtocol.kt"

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_activity,node_service,node_permissions toneBlue
class node_cellular,node_health,node_hotspot,node_publicip,node_dns,node_happy,node_ipliteral toneAmber
class node_nativeapi,node_jni,node_proxy,node_protocol,node_forward,node_state,node_udp,node_udpdns,node_purge toneMint
class node_selftest,node_clientprotocol toneRose
class node_user,node_internet toneIndigo
```

## Components

### Android app

- [Control UI](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`
- [Proxy service](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`
- [Power permissions](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/PowerPermissionHelper.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/PowerPermissionHelper.kt`

### Cellular networking

- [Cellular manager](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/CellularNetworkManager.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/network/CellularNetworkManager.kt`
- [Health classifier](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/NetworkHealthClassifier.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/network/NetworkHealthClassifier.kt`
- [LAN address discovery](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/HotspotManager.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/network/HotspotManager.kt`
- [Public IP check](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/network/PublicIPChecker.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/network/PublicIPChecker.kt`
- [DNS cache](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/DnsCache.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/DnsCache.kt`
- [Address racing](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/HappyEyeballs.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/HappyEyeballs.kt`
- [IP literal check](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/IpLiteral.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/IpLiteral.kt`

### JNI and native proxy

- [Native API](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/NativeEngine.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/NativeEngine.kt`
- [JNI bridge](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/jni_bridge.c): `app/src/main/cpp/jni_bridge.c`
- [SOCKS5 engine](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/simple-socks5.c): `app/src/main/cpp/simple-socks5.c`
- [Protocol codec](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/socks5_protocol.c): `app/src/main/cpp/socks5_protocol.c`
- [TCP forwarding](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/conn_forward.c): `app/src/main/cpp/conn_forward.c`
- [Connection state](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/conn_state.c): `app/src/main/cpp/conn_state.c`
- [UDP relay](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/udp_conn.c): `app/src/main/cpp/udp_conn.c`
- [UDP DNS support](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/udp_dns.c): `app/src/main/cpp/udp_dns.c`
- [Ghost cleanup](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/cpp/ghost_purge.c): `app/src/main/cpp/ghost_purge.c`

### Testing and diagnostics

- [Proxy self-test](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/SelfTest.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/SelfTest.kt`
- [Test protocol](https://github.com/tokyoxpa3/5g-proxy-pro/blob/main/app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ClientProtocol.kt): `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ClientProtocol.kt`

### Other components

- **Operator**
- **Internet targets**

## Connections

- Operator → Control UI: controls
- Control UI → Proxy service: starts and stops (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`)
- Control UI → Proxy self-test: runs (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`)
- Control UI → Power permissions: guides (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`)
- Proxy service → Cellular manager: requests network (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`)
- Proxy service → Health classifier: classifies health (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`)
- Proxy service → Native API: starts engine (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`)
- Proxy service → LAN address discovery: discovers LAN (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`)
- Control UI → Public IP check: checks address (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/DebugActivity.kt`)
- Proxy service → DNS cache: uses cache (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`)
- Proxy service → Address racing: orders addresses (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`)
- Proxy service → IP literal check: checks host (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/Socks5ProxyService.kt`)
- Native API → JNI bridge: calls native
- JNI bridge → Native API: calls callbacks (evidence: `app/src/main/cpp/jni_bridge.c`)
- JNI bridge → SOCKS5 engine: dispatches
- SOCKS5 engine → Internet targets: relays traffic
- SOCKS5 engine → Protocol codec: uses codec (evidence: `app/src/main/cpp/simple-socks5.c`)
- SOCKS5 engine → TCP forwarding: uses forwarding (evidence: `app/src/main/cpp/simple-socks5.c`)
- SOCKS5 engine → Connection state: uses state (evidence: `app/src/main/cpp/simple-socks5.c`)
- SOCKS5 engine → UDP relay: starts relay (evidence: `app/src/main/cpp/simple-socks5.c`)
- SOCKS5 engine → UDP DNS support: uses DNS support (evidence: `app/src/main/cpp/simple-socks5.c`)
- SOCKS5 engine → Ghost cleanup: uses cleanup (evidence: `app/src/main/cpp/simple-socks5.c`)
- Proxy self-test → Test protocol: encodes requests (evidence: `app/src/main/java/com/tokyoxpa3/androidproxy/SelfTest.kt`)
- Proxy self-test → Proxy service: tests proxy path
