# ospab/ostp architecture

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

- Interactive diagram: https://gitdiagram.com/ospab/ostp
- Repository: https://github.com/ospab/ostp

## Overview

1. **This is a Rust monorepo with one shared protocol core and several frontends.**  
   The central dependency is `ostp-core`, which implements the wire protocol, cryptography, framing, congestion/reliability logic, DNS probing, and session resumption. Everything else is a runtime wrapper around that core.

2. **The main boundary is between local traffic handling and encrypted transport.**  
   On the client side, local app traffic enters through a tunnel/proxy layer, is routed and policy-checked, then handed to a transport implementation. On the server side, the inverse happens: transport packets are decrypted/authenticated, then relayed onward to the Internet or other outbound targets.

3. **`ostp-core` is the protocol engine shared by client and server.**  
   Its submodules show the architecture: `crypto` for Noise/AEAD/obfuscation, `framing` for packet structure and padding, `congestion` for ARQ behavior, `relay` and `resumption` for session handling, and `dns` / `dnstt` for DNS-related transport support. This crate is the trust boundary for packet integrity and masking.

4. **Transport is abstracted from the protocol.**  
   The repo supports multiple carriers, including UDP and UDP-over-TCP (`uot`), with additional DNS- and XHTTP-style transport code on the client/server sides. The transport layer is where anti-DPI behavior, handshake fragmentation, junk packets, masking, and padding are applied before packets leave the host.

5. **`ostp-client` is the local endpoint process.**  
   It loads config, starts runtime services (`runner`, `signal`, `logging`), and exposes inbounds such as `local_proxy` and `tun`. It then selects an outbound such as `ostp`, `socks`, `direct`, or `block`, making the client a policy-and-routing hub rather than a single-purpose tunnel.

6. **Client traffic flow includes routing, sniffing, and NAT handling.**  
   Modules like `router`, `exclusion`, `process_lookup`, `sni_sniff`, and `udp_nat` show that the client inspects flows, decides whether they should be tunneled, and maintains UDP mappings for stateful traffic. This is the part you would diagram as “local applications → policy/routing → tunnel or bypass.”

7. **`ostp-server` is the remote termination and relay node.**  
   It contains transport listeners, dispatch logic, relay/outbound handling, and router/fallback logic. It also exposes a management API (`api.rs`) for server administration, metrics, and key-related operations, so the server has both data-plane and control-plane responsibilities.

8. **There is a separate TUN/network-stack subsystem for full-system routing.**  
   `ostp-tun`, `ostp-tun-helper`, and `netstack-smoltcp` provide cross-platform TUN integration and a user-space TCP/IP stack. This is the architecture used when the client needs to route all device traffic without relying on an external tun2socks dependency. The `netstack-smoltcp` crate is the reusable network stack/forwarding engine; the helper crates bind it to OS-specific TUN devices and route setup.

9. **Platform frontends are thin shells over the same backend concepts.**  
   `ostp-gui` is a Tauri desktop app with a JS frontend and Rust backend; `ostp-flutter` is the Android UI with `OstpVpnService`, `OstpTileService`, and a bundled `tun2socks` asset; `ostp-jni` bridges Rust client functionality into Android/Kotlin. These frontends mainly handle user interaction and platform-specific VPN/TUN integration, not protocol logic.

10. **Deployment and control are split from the protocol runtime.**  
   The repo includes prebuilt web assets for `ostp-control`, plus CI/build scripts for Rust, Android, Tauri, and Flutter. That means the architecture has a core runtime plane, a management plane, and multiple packaged UI surfaces targeting Windows, Linux, macOS, and Android.

Main entry points: [`ostp-core/src/lib.rs`](https://github.com/ospab/ostp/blob/master/ostp-core/src/lib.rs) (ostp-core), [`ostp-client/src/tunnel/mod.rs`](https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/mod.rs) (Tunnel), [`ostp-server/src/lib.rs`](https://github.com/ospab/ostp/blob/master/ostp-server/src/lib.rs) (ostp-server), [`ostp-client/src/lib.rs`](https://github.com/ospab/ostp/blob/master/ostp-client/src/lib.rs) (ostp-client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Protocol Core"]
  node_ostp_core["ostp-core<br/>protocol engine<br/>[lib.rs]"]
  node_core_crypto["Crypto<br/>[mod.rs]"]
  node_core_framing["Framing<br/>packet format<br/>[mod.rs]"]
  node_core_congestion["Congestion<br/>reliability<br/>[congestion.rs]"]
  node_core_dns["DNS<br/>[dns.rs]"]
end

subgraph group_client["Client Runtime"]
  node_ostp_client["ostp-client<br/>endpoint runtime<br/>[lib.rs]"]
  node_client_runtime["Runtime<br/>startup services<br/>[runner.rs]"]
  node_client_tunnel["Tunnel<br/>policy router<br/>[mod.rs]"]
  node_client_inbounds["Inbounds<br/>local ingress<br/>[mod.rs]"]
  node_client_outbounds["Outbounds<br/>egress selection<br/>[mod.rs]"]
  node_client_transport["Client transport<br/>carrier layer<br/>[mod.rs]"]
end

subgraph group_server["Server Runtime"]
  node_ostp_server["ostp-server<br/>server runtime<br/>[lib.rs]"]
  node_server_transport["Server transport<br/>listener layer<br/>[mod.rs]"]
  node_server_relay["Relay<br/>data plane<br/>[relay.rs]"]
  node_server_api["Admin API<br/>control plane<br/>[api.rs]"]
end

subgraph group_tun["TUN Stack"]
  node_netstack["netstack-smoltcp<br/>user-space stack<br/>[lib.rs]"]
  node_tun_helper["tun-helper<br/>platform binding<br/>[main.rs]"]
  node_ostp_tun["ostp-tun<br/>tun bindings<br/>[lib.rs]"]
end

subgraph group_frontends["Frontends"]
  node_ostp_gui["ostp-gui<br/>desktop UI<br/>[main.js]"]
  node_gui_tauri["Tauri backend<br/>desktop backend<br/>[lib.rs]"]
  node_ostp_flutter["ostp-flutter<br/>mobile UI<br/>[main.dart]"]
  node_flutter_vpn["VPN service<br/>android integration<br/>[OstpVpnService.kt]"]
  node_ostp_jni["ostp-jni<br/>jni bridge<br/>[lib.rs]"]
end

subgraph group_ops["Control and Packaging"]
  node_ostp_control["ostp-control<br/>web assets<br/>[index.html]"]
  node_ostp_cli["ostp CLI<br/>standalone app<br/>[main.rs]"]
end

node_ostp_core -->|"uses"| node_core_crypto
node_ostp_core -->|"uses"| node_core_framing
node_ostp_core -->|"uses"| node_core_congestion
node_ostp_core -->|"uses"| node_core_dns
node_ostp_client -->|"starts"| node_client_runtime
node_ostp_client -->|"routes through"| node_client_tunnel
node_client_tunnel -->|"accepts"| node_client_inbounds
node_client_tunnel -->|"selects"| node_client_outbounds
node_client_tunnel -->|"hands off"| node_client_transport
node_client_transport -->|"encapsulates via"| node_ostp_core
node_ostp_server -->|"listens on"| node_server_transport
node_ostp_server -->|"forwards via"| node_server_relay
node_ostp_server -->|"exposes"| node_server_api
node_server_transport -->|"decodes via"| node_ostp_core
node_server_relay -->|"terminates via"| node_ostp_core
node_ostp_tun -->|"embeds"| node_netstack
node_tun_helper -->|"binds"| node_ostp_tun
node_ostp_gui -->|"backs with"| node_gui_tauri
node_gui_tauri -->|"controls"| node_ostp_client
node_ostp_flutter -->|"uses"| node_flutter_vpn
node_ostp_flutter -->|"bridges to"| node_ostp_jni
node_ostp_jni -->|"wraps"| node_ostp_client
node_ostp_control -.->|"manages"| node_ostp_server
node_ostp_cli -->|"probes"| node_ostp_core

click node_ostp_core "https://github.com/ospab/ostp/blob/master/ostp-core/src/lib.rs"
click node_core_crypto "https://github.com/ospab/ostp/blob/master/ostp-core/src/crypto/mod.rs"
click node_core_framing "https://github.com/ospab/ostp/blob/master/ostp-core/src/framing/mod.rs"
click node_core_congestion "https://github.com/ospab/ostp/blob/master/ostp-core/src/congestion.rs"
click node_core_dns "https://github.com/ospab/ostp/blob/master/ostp-core/src/dns.rs"
click node_ostp_client "https://github.com/ospab/ostp/blob/master/ostp-client/src/lib.rs"
click node_client_runtime "https://github.com/ospab/ostp/blob/master/ostp-client/src/runner.rs"
click node_client_tunnel "https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/mod.rs"
click node_client_inbounds "https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/inbounds/mod.rs"
click node_client_outbounds "https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/outbounds/mod.rs"
click node_client_transport "https://github.com/ospab/ostp/blob/master/ostp-client/src/transport/mod.rs"
click node_ostp_server "https://github.com/ospab/ostp/blob/master/ostp-server/src/lib.rs"
click node_server_transport "https://github.com/ospab/ostp/blob/master/ostp-server/src/transport/mod.rs"
click node_server_relay "https://github.com/ospab/ostp/blob/master/ostp-server/src/relay.rs"
click node_server_api "https://github.com/ospab/ostp/blob/master/ostp-server/src/api.rs"
click node_netstack "https://github.com/ospab/ostp/blob/master/netstack-smoltcp/src/lib.rs"
click node_tun_helper "https://github.com/ospab/ostp/blob/master/ostp-tun-helper/src/main.rs"
click node_ostp_tun "https://github.com/ospab/ostp/blob/master/ostp-tun/src/lib.rs"
click node_ostp_gui "https://github.com/ospab/ostp/blob/master/ostp-gui/src/main.js"
click node_gui_tauri "https://github.com/ospab/ostp/blob/master/ostp-gui/src-tauri/src/lib.rs"
click node_ostp_flutter "https://github.com/ospab/ostp/blob/master/ostp-flutter/lib/main.dart"
click node_flutter_vpn "https://github.com/ospab/ostp/blob/master/ostp-flutter/android/app/src/main/kotlin/com/ospab/ostp_client/OstpVpnService.kt"
click node_ostp_jni "https://github.com/ospab/ostp/blob/master/ostp-jni/src/lib.rs"
click node_ostp_control "https://github.com/ospab/ostp/blob/master/ostp-control/dist/index.html"
click node_ostp_cli "https://github.com/ospab/ostp/blob/master/ostp/src/main.rs"

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_ostp_core,node_core_crypto,node_core_framing,node_core_congestion,node_core_dns toneBlue
class node_ostp_client,node_client_runtime,node_client_tunnel,node_client_inbounds,node_client_outbounds,node_client_transport toneAmber
class node_ostp_server,node_server_transport,node_server_relay,node_server_api toneMint
class node_netstack,node_tun_helper,node_ostp_tun toneRose
class node_ostp_gui,node_gui_tauri,node_ostp_flutter,node_flutter_vpn,node_ostp_jni toneIndigo
class node_ostp_control,node_ostp_cli toneTeal
```

## Components

### Protocol Core

Shared wire-protocol and crypto engine used by all runtimes.

- [ostp-core](https://github.com/ospab/ostp/blob/master/ostp-core/src/lib.rs): protocol engine · Shared protocol implementation: crypto, framing, congestion, relay, resumption, and DNS support. · `ostp-core/src/lib.rs`
- [Crypto](https://github.com/ospab/ostp/blob/master/ostp-core/src/crypto/mod.rs): wire crypto · Noise, AEAD, obfuscation, and reality primitives. · `ostp-core/src/crypto/mod.rs`
- [Framing](https://github.com/ospab/ostp/blob/master/ostp-core/src/framing/mod.rs): packet format · Packet structure, padding, and websocket-style framing. · `ostp-core/src/framing/mod.rs`
- [Congestion](https://github.com/ospab/ostp/blob/master/ostp-core/src/congestion.rs): reliability · ARQ/congestion behavior for protocol delivery. · `ostp-core/src/congestion.rs`
- [DNS](https://github.com/ospab/ostp/blob/master/ostp-core/src/dns.rs): dns transport · DNS probing and DNS-based transport support. · `ostp-core/src/dns.rs`

### Client Runtime

Local endpoint that handles apps, policy, routing, and outbound selection.

- [ostp-client](https://github.com/ospab/ostp/blob/master/ostp-client/src/lib.rs): endpoint runtime · Local client process for config, runtime services, inbounds, routing, and outbounds. · `ostp-client/src/lib.rs`
- [Runtime](https://github.com/ospab/ostp/blob/master/ostp-client/src/runner.rs): startup services · Runner, signals, and logging for the client process. · `ostp-client/src/runner.rs`
- [Tunnel](https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/mod.rs): policy router · Traffic classification, routing, exclusions, sniffing, and UDP NAT. · `ostp-client/src/tunnel/mod.rs`
- [Inbounds](https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/inbounds/mod.rs): local ingress · Local proxy and TUN ingress points for application traffic. · `ostp-client/src/tunnel/inbounds/mod.rs`
- [Outbounds](https://github.com/ospab/ostp/blob/master/ostp-client/src/tunnel/outbounds/mod.rs): egress selection · Policy targets such as OSTP, SOCKS, direct, or block. · `ostp-client/src/tunnel/outbounds/mod.rs`
- [Client transport](https://github.com/ospab/ostp/blob/master/ostp-client/src/transport/mod.rs): carrier layer · Client-side transport adapters such as DNS and XHTTP-style transport. · `ostp-client/src/transport/mod.rs`

### Server Runtime

Remote terminator that authenticates traffic and relays it onward.

- [ostp-server](https://github.com/ospab/ostp/blob/master/ostp-server/src/lib.rs): server runtime · Remote termination node with relay, dispatch, router, and admin API. · `ostp-server/src/lib.rs`
- [Server transport](https://github.com/ospab/ostp/blob/master/ostp-server/src/transport/mod.rs): listener layer · UDP, DNS, and UOT transport listeners/encoders for inbound packets. · `ostp-server/src/transport/mod.rs`
- [Relay](https://github.com/ospab/ostp/blob/master/ostp-server/src/relay.rs): data plane · Dispatch, outbound forwarding, relay handling, and fallback logic. · `ostp-server/src/relay.rs`
- [Admin API](https://github.com/ospab/ostp/blob/master/ostp-server/src/api.rs): control plane · Management interface for server operations, metrics, and key-related actions. · `ostp-server/src/api.rs`

### TUN Stack

Reusable virtual-network and user-space stack components.

- [netstack-smoltcp](https://github.com/ospab/ostp/blob/master/netstack-smoltcp/src/lib.rs): user-space stack · Reusable TCP/IP forwarding engine for full-system routing. · `netstack-smoltcp/src/lib.rs`
- [tun-helper](https://github.com/ospab/ostp/blob/master/ostp-tun-helper/src/main.rs): platform binding · OS-specific TUN setup and routing helper binary. · `ostp-tun-helper/src/main.rs`
- [ostp-tun](https://github.com/ospab/ostp/blob/master/ostp-tun/src/lib.rs): tun bindings · Cross-platform TUN abstraction and route integration for desktop/mobile clients. · `ostp-tun/src/lib.rs`

### Frontends

Desktop, mobile, and JNI shells around the shared backend.

- [ostp-gui](https://github.com/ospab/ostp/blob/master/ostp-gui/src/main.js): desktop UI · Tauri desktop shell with JS frontend and Rust backend. · `ostp-gui/src/main.js`
- [Tauri backend](https://github.com/ospab/ostp/blob/master/ostp-gui/src-tauri/src/lib.rs): desktop backend · Rust backend for desktop integration and DNS/IPC helpers. · `ostp-gui/src-tauri/src/lib.rs`
- [ostp-flutter](https://github.com/ospab/ostp/blob/master/ostp-flutter/lib/main.dart): mobile UI · Flutter Android frontend and VPN service integration. · `ostp-flutter/lib/main.dart`
- [VPN service](https://github.com/ospab/ostp/blob/master/ostp-flutter/android/app/src/main/kotlin/com/ospab/ostp_client/OstpVpnService.kt): android integration · Android VPN/tile services and bundled tun2socks asset. · `ostp-flutter/android/app/src/main/kotlin/com/ospab/ostp_client/OstpVpnService.kt`
- [ostp-jni](https://github.com/ospab/ostp/blob/master/ostp-jni/src/lib.rs): jni bridge · Rust-to-Kotlin bridge for Android client functionality. · `ostp-jni/src/lib.rs`

### Control and Packaging

Build artifacts, web control assets, and the standalone CLI surface.

- [ostp-control](https://github.com/ospab/ostp/blob/master/ostp-control/dist/index.html): web assets · Prebuilt control-plane frontend assets shipped with the repo. · `ostp-control/dist/index.html`
- [ostp CLI](https://github.com/ospab/ostp/blob/master/ostp/src/main.rs): standalone app · Repository-root binary surface and DNS probing entrypoint. · `ostp/src/main.rs`

## Connections

- ostp-core → Crypto: uses · Core protocol relies on cryptographic primitives.
- ostp-core → Framing: uses · Core protocol defines packet framing and padding.
- ostp-core → Congestion: uses · Core protocol handles reliability and congestion behavior.
- ostp-core → DNS: uses · Core protocol includes DNS probing and DNS transport support.
- ostp-client → Runtime: starts · Client process initializes runtime services.
- ostp-client → Tunnel: routes through · Client funnels local traffic into tunnel policy.
- Tunnel → Inbounds: accepts · Tunnel receives traffic from local ingress points.
- Tunnel → Outbounds: selects · Tunnel chooses bypass, block, or encrypted egress.
- Tunnel → Client transport: hands off · Tunnel forwards tunneled traffic to transport adapters.
- Client transport → ostp-core: encapsulates via · Client transport uses the shared protocol engine.
- ostp-server → Server transport: listens on · Server accepts packets through transport listeners.
- ostp-server → Relay: forwards via · Server relay handles decrypted traffic and outbound delivery.
- ostp-server → Admin API: exposes · Server publishes management/control APIs.
- Server transport → ostp-core: decodes via · Server transport relies on the shared protocol engine.
- Relay → ostp-core: terminates via · Relay uses protocol session handling and resumption.
- ostp-tun → netstack-smoltcp: embeds · TUN layer can feed a reusable user-space network stack.
- tun-helper → ostp-tun: binds · Helper connects OS TUN devices and routes to the shared TUN layer.
- ostp-gui → Tauri backend: backs with · Desktop UI is paired with a Rust Tauri backend.
- Tauri backend → ostp-client: controls · Desktop backend drives the client runtime.
- ostp-flutter → VPN service: uses · Flutter app delegates VPN/TUN handling to Android services.
- ostp-flutter → ostp-jni: bridges to · Flutter/mobile surface can interoperate with the JNI bridge.
- ostp-jni → ostp-client: wraps · JNI exposes client capabilities to Kotlin/Android.
- ostp-control → ostp-server: manages · Static control assets serve the server management plane.
- ostp CLI → ostp-core: probes · Standalone CLI includes DNS probing around the shared core.
