# p1neapplexpress/openflux architecture

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

- Interactive diagram: https://gitdiagram.com/p1neapplexpress/openflux
- Repository: https://github.com/p1neapplexpress/openflux

## Overview

OpenFlux is an IPv4 TCP/UDP tunneling stack with pluggable carriers and L3 or L4 exit backends. The principal workflow configures a client, establishes a multi-transport session, carries packets to an exit, and forwards them to the Internet. The graph also preserves documented proxy/VPN entry points, link sharing, node provisioning, and captcha-cookie handling. Some capability links rely on README descriptions because their implementation was not sampled; unsampled source is not treated as inspected.

Main entry points: [`main.go`](https://github.com/p1neapplexpress/openflux/blob/main/main.go) (CLI runtime), [`transport/session.go`](https://github.com/p1neapplexpress/openflux/blob/main/transport/session.go) (Session protocol), [`transport/manager/manager.go`](https://github.com/p1neapplexpress/openflux/blob/main/transport/manager/manager.go) (Transport manager), [`tunnel/exit.go`](https://github.com/p1neapplexpress/openflux/blob/main/tunnel/exit.go) (Exit selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and control"]
  node_main["CLI runtime<br/>[main.go]"]
  node_socks["SOCKS5 proxy<br/>[socks5.go]"]
  node_mobile["Mobile bridge<br/>[mobile.go]"]
  node_ipc["App IPC<br/>[server.go]"]
  node_captcha["Captcha cookies<br/>[manager.go]"]
end

subgraph group_session["Session and carriers"]
  node_session["Session protocol<br/>[session.go]"]
  node_manager["Transport manager<br/>[manager.go]"]
  node_codec["Batch codec<br/>[batched.go]"]
  node_carriers["Pluggable carriers"]
  node_phpbox["PHPBox relay<br/>[mux.go]"]
end

subgraph group_forward["Tunnel forwarding"]
  node_tun["Client packet tunnel<br/>[tunnel.go]"]
  node_stream["Stream proxy mode<br/>[streamproxy.go]"]
  node_exit["Exit selection<br/>[exit.go]"]
  node_l3["Raw L3 backend<br/>[l3.go]"]
  node_l4["L4 gVisor backend<br/>[tunnel.go]"]
end

subgraph group_provision["Sharing and deployment"]
  node_share["Share links and QR<br/>[share.go]"]
  node_wizard["Node wizard<br/>[node_wizard.go]"]
  node_provision["Node provisioning<br/>[provision.go]"]
  node_phpdeploy["PHPBox exit service<br/>[phpbox.php]"]
  node_cupsdeploy["Cups exit service<br/>[cupsexit.php]"]
end

node_user(("Client user"))
node_internet(("Internet destination"))

node_user -->|"configures"| node_main
node_main -->|"builds session"| node_manager
node_manager -->|"starts session"| node_session
node_session -->|"batches packets"| node_codec
node_manager -.->|"starts transports"| node_carriers
node_main -->|"runs packet tunnel"| node_tun
node_main -->|"serves proxy"| node_socks
node_main -->|"starts stream mode"| node_stream
node_tun -->|"sends packets"| node_session
node_session -->|"delivers packets"| node_exit
node_exit -->|"selects raw mode"| node_l3
node_exit -->|"selects proxy mode"| node_l4
node_l3 -->|"forwards packets"| node_internet
node_l4 -->|"redials flows"| node_internet
node_mobile -->|"builds session"| node_session
node_mobile -.->|"bridges app"| node_ipc
node_ipc -->|"offers cookies"| node_captcha
node_manager -->|"requests cookies"| node_captcha
node_user -->|"makes share link"| node_share
node_user -->|"deploys node"| node_wizard
node_wizard -.->|"configures host"| node_provision
node_provision -.->|"deploys PHPBox"| node_phpdeploy
node_carriers -.->|"includes relay client"| node_phpbox
node_cupsdeploy -.->|"provides Cups exit"| node_carriers

click node_main "https://github.com/p1neapplexpress/openflux/blob/main/main.go"
click node_socks "https://github.com/p1neapplexpress/openflux/blob/main/socks5/socks5.go"
click node_mobile "https://github.com/p1neapplexpress/openflux/blob/main/mobile/mobile.go"
click node_ipc "https://github.com/p1neapplexpress/openflux/blob/main/transport/ipc/server.go"
click node_captcha "https://github.com/p1neapplexpress/openflux/blob/main/transport/manager/manager.go"
click node_session "https://github.com/p1neapplexpress/openflux/blob/main/transport/session.go"
click node_manager "https://github.com/p1neapplexpress/openflux/blob/main/transport/manager/manager.go"
click node_codec "https://github.com/p1neapplexpress/openflux/blob/main/transport/batched.go"
click node_carriers "https://github.com/p1neapplexpress/openflux/tree/main/transport"
click node_phpbox "https://github.com/p1neapplexpress/openflux/blob/main/transport/phpbox/mux.go"
click node_tun "https://github.com/p1neapplexpress/openflux/blob/main/tunnel/tunnel.go"
click node_stream "https://github.com/p1neapplexpress/openflux/blob/main/streamproxy/streamproxy.go"
click node_exit "https://github.com/p1neapplexpress/openflux/blob/main/tunnel/exit.go"
click node_l3 "https://github.com/p1neapplexpress/openflux/blob/main/tunnel/l3/l3.go"
click node_l4 "https://github.com/p1neapplexpress/openflux/blob/main/tunnel/tunnel.go"
click node_share "https://github.com/p1neapplexpress/openflux/blob/main/share/share.go"
click node_wizard "https://github.com/p1neapplexpress/openflux/blob/main/node_wizard.go"
click node_provision "https://github.com/p1neapplexpress/openflux/blob/main/provision/provision.go"
click node_phpdeploy "https://github.com/p1neapplexpress/openflux/blob/main/deploy/phpbox/phpbox.php"
click node_cupsdeploy "https://github.com/p1neapplexpress/openflux/blob/main/deploy/phpbox/cupsexit.php"

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_main,node_socks,node_mobile,node_ipc,node_captcha,node_user toneBlue
class node_session,node_manager,node_codec,node_carriers,node_phpbox toneAmber
class node_tun,node_stream,node_exit,node_l3,node_l4 toneMint
class node_share,node_wizard,node_provision,node_phpdeploy,node_cupsdeploy toneRose
class node_internet toneIndigo
```

## Components

### Client and control

- [CLI runtime](https://github.com/p1neapplexpress/openflux/blob/main/main.go): `main.go`
- [SOCKS5 proxy](https://github.com/p1neapplexpress/openflux/blob/main/socks5/socks5.go): `socks5/socks5.go`
- [Mobile bridge](https://github.com/p1neapplexpress/openflux/blob/main/mobile/mobile.go): `mobile/mobile.go`
- [App IPC](https://github.com/p1neapplexpress/openflux/blob/main/transport/ipc/server.go): `transport/ipc/server.go`
- [Captcha cookies](https://github.com/p1neapplexpress/openflux/blob/main/transport/manager/manager.go): `transport/manager/manager.go`

### Session and carriers

- [Session protocol](https://github.com/p1neapplexpress/openflux/blob/main/transport/session.go): `transport/session.go`
- [Transport manager](https://github.com/p1neapplexpress/openflux/blob/main/transport/manager/manager.go): `transport/manager/manager.go`
- [Batch codec](https://github.com/p1neapplexpress/openflux/blob/main/transport/batched.go): `transport/batched.go`
- [Pluggable carriers](https://github.com/p1neapplexpress/openflux/tree/main/transport): `transport`
- [PHPBox relay](https://github.com/p1neapplexpress/openflux/blob/main/transport/phpbox/mux.go): `transport/phpbox/mux.go`

### Tunnel forwarding

- [Client packet tunnel](https://github.com/p1neapplexpress/openflux/blob/main/tunnel/tunnel.go): `tunnel/tunnel.go`
- [Stream proxy mode](https://github.com/p1neapplexpress/openflux/blob/main/streamproxy/streamproxy.go): `streamproxy/streamproxy.go`
- [Exit selection](https://github.com/p1neapplexpress/openflux/blob/main/tunnel/exit.go): `tunnel/exit.go`
- [Raw L3 backend](https://github.com/p1neapplexpress/openflux/blob/main/tunnel/l3/l3.go): `tunnel/l3/l3.go`
- [L4 gVisor backend](https://github.com/p1neapplexpress/openflux/blob/main/tunnel/tunnel.go): `tunnel/tunnel.go`

### Sharing and deployment

- [Share links and QR](https://github.com/p1neapplexpress/openflux/blob/main/share/share.go): `share/share.go`
- [Node wizard](https://github.com/p1neapplexpress/openflux/blob/main/node_wizard.go): `node_wizard.go`
- [Node provisioning](https://github.com/p1neapplexpress/openflux/blob/main/provision/provision.go): `provision/provision.go`
- [PHPBox exit service](https://github.com/p1neapplexpress/openflux/blob/main/deploy/phpbox/phpbox.php): `deploy/phpbox/phpbox.php`
- [Cups exit service](https://github.com/p1neapplexpress/openflux/blob/main/deploy/phpbox/cupsexit.php): `deploy/phpbox/cupsexit.php`

### Other components

- **Client user**
- **Internet destination**

## Connections

- Client user → CLI runtime: configures (evidence: `README.md`)
- CLI runtime → Transport manager: builds session (evidence: `main.go`)
- Transport manager → Session protocol: starts session (evidence: `transport/manager/manager.go`)
- Session protocol → Batch codec: batches packets (evidence: `transport/session.go`)
- Transport manager → Pluggable carriers: starts transports (evidence: `transport/manager/manager.go`)
- CLI runtime → Client packet tunnel: runs packet tunnel (evidence: `main.go`)
- CLI runtime → SOCKS5 proxy: serves proxy (evidence: `main.go`)
- CLI runtime → Stream proxy mode: starts stream mode (evidence: `main.go`)
- Client packet tunnel → Session protocol: sends packets (evidence: `tunnel/tunnel.go`)
- Session protocol → Exit selection: delivers packets (evidence: `README.md`)
- Exit selection → Raw L3 backend: selects raw mode (evidence: `README.md`)
- Exit selection → L4 gVisor backend: selects proxy mode (evidence: `README.md`)
- Raw L3 backend → Internet destination: forwards packets (evidence: `README.md`)
- L4 gVisor backend → Internet destination: redials flows (evidence: `README.md`)
- Mobile bridge → Session protocol: builds session
- Mobile bridge → App IPC: bridges app
- App IPC → Captcha cookies: offers cookies
- Transport manager → Captcha cookies: requests cookies (evidence: `transport/manager/manager.go`)
- Client user → Share links and QR: makes share link (evidence: `README.md`)
- Client user → Node wizard: deploys node (evidence: `README.md`)
- Node wizard → Node provisioning: configures host
- Node provisioning → PHPBox exit service: deploys PHPBox
- Pluggable carriers → PHPBox relay: includes relay client
- Cups exit service → Pluggable carriers: provides Cups exit
