# sdmeth/openflux architecture

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

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

## Overview

OpenFlux is a cross-platform IPv4 TCP/UDP tunneling system. A client captures traffic through a local SOCKS5 or platform tunnel, carries packets over one or more pluggable transports, and delivers them through an exit node using either raw L3 forwarding or an L4 userspace proxy. The graph emphasizes that workflow and the session/transport layer, while retaining the iOS entry points and the documented transport and backend capabilities. Some subsystem links are documented by the README; unsampled implementation details are not inferred.

Main entry points: [`transport/session.go`](https://github.com/sdmeth/openflux/blob/main/transport/session.go) (Encrypted session), [`transport/manager/manager.go`](https://github.com/sdmeth/openflux/blob/main/transport/manager/manager.go) (Transport manager), [`tunnel/exit.go`](https://github.com/sdmeth/openflux/blob/main/tunnel/exit.go) (Exit routing), [`main.go`](https://github.com/sdmeth/openflux/blob/main/main.go) (CLI roles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client entry"]
  node_cli["CLI roles<br/>[main.go]"]
  node_socks["SOCKS5 proxy<br/>[socks5.go]"]
  node_platformtun["Platform tunnels<br/>[tun_darwin.go]"]
  node_iosui["iOS controls<br/>[ContentView.swift]"]
  node_iostunnel["iOS VPN tunnel"]
  node_iosprovider["Packet provider"]
end

subgraph group_session["Session and transports"]
  node_session["Encrypted session<br/>[session.go]"]
  node_manager["Transport manager<br/>[manager.go]"]
  node_codec["Batch codec<br/>[batched.go]"]
  node_factory["Transport factory"]
  node_providers["Transport providers"]
end

subgraph group_exit["Exit forwarding"]
  node_exitrouter["Exit routing<br/>[exit.go]"]
  node_l3["Raw L3 backend<br/>[l3.go]"]
  node_l4["L4 proxy backend<br/>[proxy_exit.go]"]
end

subgraph group_mobile["Mobile integration"]
  node_ipcserver["IPC server<br/>[server.go]"]
  node_ipchandler["IPC handler<br/>[ipc_handler.go]"]
  node_mobileapi["Mobile session API<br/>[session.go]"]
end

node_user(("User traffic"))
node_internet(("Internet services"))

node_user -.->|"routes through"| node_socks
node_user -.->|"routes through"| node_platformtun
node_iosui -->|"starts proxy"| node_iostunnel
node_iosui -->|"starts VPN"| node_iosprovider
node_iostunnel -.->|"starts core"| node_session
node_iosprovider -.->|"sends packets"| node_session
node_cli -.->|"builds transports"| node_factory
node_cli -.->|"starts session"| node_session
node_socks -.->|"carries packets"| node_session
node_platformtun -.->|"carries packets"| node_session
node_session -->|"sends packets"| node_codec
node_manager -->|"registers transports"| node_session
node_manager -->|"creates transports"| node_factory
node_session -.->|"dispatches traffic"| node_providers
node_providers -.->|"connects via"| node_internet
node_session -.->|"delivers packets"| node_exitrouter
node_exitrouter -.->|"selects backend"| node_l3
node_exitrouter -.->|"selects backend"| node_l4
node_l3 -.->|"forwards packets"| node_internet
node_l4 -.->|"dials services"| node_internet
node_ipcserver -->|"dispatches messages"| node_ipchandler
node_ipchandler -->|"forwards cookies"| node_manager
node_mobileapi -->|"builds session"| node_session
node_mobileapi -->|"registers transports"| node_manager

click node_cli "https://github.com/sdmeth/openflux/blob/main/main.go"
click node_socks "https://github.com/sdmeth/openflux/blob/main/socks5/socks5.go"
click node_platformtun "https://github.com/sdmeth/openflux/blob/main/tun_darwin.go"
click node_iosui "https://github.com/sdmeth/openflux/blob/main/ios-app/OpenFlux/ContentView.swift"
click node_iostunnel "https://github.com/sdmeth/openflux/blob/main/ios-app/OpenFlux/TunnelController.swift"
click node_iosprovider "https://github.com/sdmeth/openflux/blob/main/ios-app/OpenFluxTunnel/PacketTunnelProvider.swift"
click node_session "https://github.com/sdmeth/openflux/blob/main/transport/session.go"
click node_manager "https://github.com/sdmeth/openflux/blob/main/transport/manager/manager.go"
click node_codec "https://github.com/sdmeth/openflux/blob/main/transport/batched.go"
click node_factory "https://github.com/sdmeth/openflux/blob/main/transport_factory.go"
click node_providers "https://github.com/sdmeth/openflux/tree/main/transport"
click node_exitrouter "https://github.com/sdmeth/openflux/blob/main/tunnel/exit.go"
click node_l3 "https://github.com/sdmeth/openflux/blob/main/tunnel/l3/l3.go"
click node_l4 "https://github.com/sdmeth/openflux/blob/main/tunnel/proxy_exit.go"
click node_ipcserver "https://github.com/sdmeth/openflux/blob/main/transport/ipc/server.go"
click node_ipchandler "https://github.com/sdmeth/openflux/blob/main/ipc_handler.go"
click node_mobileapi "https://github.com/sdmeth/openflux/blob/main/mobile/session.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_cli,node_socks,node_platformtun,node_iosui,node_iostunnel,node_iosprovider,node_user toneBlue
class node_session,node_manager,node_codec,node_factory,node_providers toneAmber
class node_exitrouter,node_l3,node_l4 toneMint
class node_ipcserver,node_ipchandler,node_mobileapi toneRose
class node_internet toneIndigo
```

## Components

### Client entry

- [CLI roles](https://github.com/sdmeth/openflux/blob/main/main.go): `main.go`
- [SOCKS5 proxy](https://github.com/sdmeth/openflux/blob/main/socks5/socks5.go): `socks5/socks5.go`
- [Platform tunnels](https://github.com/sdmeth/openflux/blob/main/tun_darwin.go): `tun_darwin.go`
- [iOS controls](https://github.com/sdmeth/openflux/blob/main/ios-app/OpenFlux/ContentView.swift): `ios-app/OpenFlux/ContentView.swift`
- [iOS VPN tunnel](https://github.com/sdmeth/openflux/blob/main/ios-app/OpenFlux/TunnelController.swift): `ios-app/OpenFlux/TunnelController.swift`
- [Packet provider](https://github.com/sdmeth/openflux/blob/main/ios-app/OpenFluxTunnel/PacketTunnelProvider.swift): `ios-app/OpenFluxTunnel/PacketTunnelProvider.swift`

### Session and transports

- [Encrypted session](https://github.com/sdmeth/openflux/blob/main/transport/session.go): `transport/session.go`
- [Transport manager](https://github.com/sdmeth/openflux/blob/main/transport/manager/manager.go): `transport/manager/manager.go`
- [Batch codec](https://github.com/sdmeth/openflux/blob/main/transport/batched.go): `transport/batched.go`
- [Transport factory](https://github.com/sdmeth/openflux/blob/main/transport_factory.go): `transport_factory.go`
- [Transport providers](https://github.com/sdmeth/openflux/tree/main/transport): `transport`

### Exit forwarding

- [Exit routing](https://github.com/sdmeth/openflux/blob/main/tunnel/exit.go): `tunnel/exit.go`
- [Raw L3 backend](https://github.com/sdmeth/openflux/blob/main/tunnel/l3/l3.go): `tunnel/l3/l3.go`
- [L4 proxy backend](https://github.com/sdmeth/openflux/blob/main/tunnel/proxy_exit.go): `tunnel/proxy_exit.go`

### Mobile integration

- [IPC server](https://github.com/sdmeth/openflux/blob/main/transport/ipc/server.go): `transport/ipc/server.go`
- [IPC handler](https://github.com/sdmeth/openflux/blob/main/ipc_handler.go): `ipc_handler.go`
- [Mobile session API](https://github.com/sdmeth/openflux/blob/main/mobile/session.go): `mobile/session.go`

### Other components

- **User traffic**
- **Internet services**

## Connections

- User traffic → SOCKS5 proxy: routes through (evidence: `README.md`)
- User traffic → Platform tunnels: routes through (evidence: `README.md`)
- iOS controls → iOS VPN tunnel: starts proxy (evidence: `ios-app/OpenFlux/ContentView.swift`)
- iOS controls → Packet provider: starts VPN (evidence: `ios-app/OpenFlux/ContentView.swift`)
- iOS VPN tunnel → Encrypted session: starts core
- Packet provider → Encrypted session: sends packets
- CLI roles → Transport factory: builds transports (evidence: `README.md`)
- CLI roles → Encrypted session: starts session (evidence: `README.md`)
- SOCKS5 proxy → Encrypted session: carries packets (evidence: `README.md`)
- Platform tunnels → Encrypted session: carries packets (evidence: `README.md`)
- Encrypted session → Batch codec: sends packets (evidence: `transport/session.go`)
- Transport manager → Encrypted session: registers transports (evidence: `transport/manager/manager.go`)
- Transport manager → Transport factory: creates transports (evidence: `transport/manager/manager.go`)
- Encrypted session → Transport providers: dispatches traffic (evidence: `README.md`)
- Transport providers → Internet services: connects via (evidence: `README.md`)
- Encrypted session → Exit routing: delivers packets (evidence: `README.md`)
- Exit routing → Raw L3 backend: selects backend (evidence: `README.md`)
- Exit routing → L4 proxy backend: selects backend (evidence: `README.md`)
- Raw L3 backend → Internet services: forwards packets (evidence: `README.md`)
- L4 proxy backend → Internet services: dials services (evidence: `README.md`)
- IPC server → IPC handler: dispatches messages (evidence: `transport/ipc/server.go`)
- IPC handler → Transport manager: forwards cookies (evidence: `ipc_handler.go`)
- Mobile session API → Encrypted session: builds session (evidence: `mobile/session.go`)
- Mobile session API → Transport manager: registers transports (evidence: `mobile/session.go`)
