# kulikov0/whitelist-bypass architecture

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

- Interactive diagram: https://gitdiagram.com/kulikov0/whitelist-bypass
- Repository: https://github.com/kulikov0/whitelist-bypass

## Overview

1. Overall shape

This repo is a multi-platform “tunnel over video call” system. The architectural center is a shared Go transport stack in `relay/`, while the endpoints are split into creator-side apps and joiner-side apps for Android, iOS, desktop, and headless Linux use.

2. Core data path

The important end-to-end flow is:
system traffic on the joiner device → local tunnel/proxy layer → Go SOCKS5 proxy → Pion-based tunnel session → platform SFU (VK / Telemost / WB Stream) → matching creator-side session → outbound Internet via the creator machine.

The tunnel payload can ride either DataChannel traffic or encoded VP8 video frames, depending on mode and platform constraints.

3. Shared transport/runtime boundary: `relay/`

`relay/` is the shared low-level engine. It contains:
- SOCKS5 proxying and client plumbing
- tunnel protocol framing and multiplexing
- obfuscation
- platform-specific tunnel bridges
- Go mobile bindings for Android/iOS

This is the main boundary where “local network proxy semantics” turn into “traffic embedded in a call.”

4. Tunnel modes

There are two transport modes in the repo:
- DC mode: data goes over SCTP DataChannels.
- Video mode: data is encoded into VP8 video streams.

Both modes share the same higher-level tunnel framing and multiplexing; the difference is only the carrier over the SFU. Video mode is especially important for platforms that throttle or restrict DataChannels.

5. Creator-side implementations

The creator side is split into two architectural paths:

- Legacy browser path: `creator-app/` Electron UI plus injected JS hooks in `hooks/`
- Headless path: pure Go binaries under `headless/`

The headless path is the preferred architecture in the README because it talks directly to the platform APIs and Pion, avoiding browser automation.

6. Creator app: Electron orchestration

`creator-app/` is a desktop control plane. It provides the UI for selecting platform and tunnel mode, and can either:
- run the legacy browser flow with tab management and JS hooks, or
- spawn the headless Go binaries and supervise them

It also handles packaging of hooks, binary discovery, and user-facing link generation/sharing.

7. Headless creator family

The headless binaries are separated by platform:
- `headless/vk/`
- `headless/telemost/`
- `headless/wbstream/`

These create or join calls through platform-specific APIs and then attach the tunnel session directly. Supporting companions exist for joining:
- `headless/telemost-joiner/`
- `headless/wbstream-joiner/`

There is also `headless/vk-bot/`, a VK Long Poll bot that triggers headless creators server-side and returns join links.

8. Joiner-side Android architecture

`android-app/` is the primary censored-network client. Its stack is:
- `VpnService` capture of all device traffic
- `tun2socks`-style conversion from IP packets to SOCKS5
- local Go proxy/tunnel service
- headless Pion session joined into the call

This app also includes a legacy WebView-based fallback for VK browser hooks, but that path is secondary.

9. Joiner-side iOS architecture

`ios-proxy-app/` is narrower in scope than Android: it exposes a local SOCKS5 proxy backed by the shared Go mobile framework (`Mobile.xcframework`). It does not implement a full system VPN in this repo; instead, the device or an app can be pointed at the SOCKS endpoint.

10. Legacy browser automation layer

The browser-based flow is supported by JS hooks in `hooks/` and mirrored assets in `android-app/app/src/main/assets/`. These scripts patch the calling pages for:
- autoplay / audio muting
- call joining
- video handling
- platform-specific DOM interactions

This layer only matters for the older browser-based VK/Telemost path and is explicitly not used by the headless Go path.

11. Platform-specific signaling and call logic

Inside `relay/` and `headless/`, each platform has its own signaling/call layer:
- VK-specific signaling, cookies, peer/call handling
- Telemost API and tunnel relay integration
- WB Stream session logic and LiveKit-backed mechanics

So the architecture is not a single generic signaling backend; it is a set of per-platform adapters feeding the same tunnel core.

12. Support infrastructure and build/runtime boundaries

The repo includes build and release automation for multiple targets:
- Android, iOS, desktop Electron apps, headless Linux binaries, and Docker builds
- Go + Node.js + Android SDK/NDK + Xcode/macOS as needed per target

The `.github` workflow and scripts mainly orchestrate packaging; they do not change the runtime architecture, but they reflect that this is a polyglot, multi-artifact system.

13. Observability and operational control

The Android app has a dedicated logs UI, status indicators, and tunnel/service state tracking. The Go side also exposes status/logging concepts used by desktop and headless tooling. In an architecture diagram, this is worth showing as a side-channel from tunnel services to UI/log viewers, not part of the data plane.

14. Test and validation boundary

`headless/tests/` contains end-to-end smoke tests for the platform-specific headless flows. These validate that creator/joiner signaling and tunnel establishment work against real platforms, which is important because much of the system depends on external call services.

15. External dependencies that matter architecturally

The system depends on:
- platform call/SFU services: VK Call, Yandex Telemost, WB Stream
- Pion WebRTC in the Go implementation
- Android VpnService / tun2socks behavior
- Electron and WebView for legacy browser automation
- Go mobile bindings for iOS/Android integration

These are the major boundaries where this repo crosses into platform APIs or external infrastructure.

Main entry points: [`creator-app`](https://github.com/kulikov0/whitelist-bypass/tree/main/creator-app) (Creator app), [`relay/main.go`](https://github.com/kulikov0/whitelist-bypass/blob/main/relay/main.go) (Relay core), [`relay/pion`](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/pion) (Pion bridge), [`android-app/app/src/main/java/bypass/whitelist`](https://github.com/kulikov0/whitelist-bypass/tree/main/android-app/app/src/main/java/bypass/whitelist) (Android app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core transport"]
  node_relay_main["Relay core<br/>Go transport stack<br/>[main.go]"]
  node_relay_common["Common net<br/>Proxy/runtime utils"]
  node_relay_tunnel["Tunnel core<br/>Framing carriers"]
  node_relay_pion["Pion bridge<br/>WebRTC bindings"]
end

subgraph group_creator["Creator apps"]
  node_creator_app["Creator app<br/>Electron control plane"]
  node_hooks["Browser hooks<br/>Injected scripts"]
end

subgraph group_joiner["Joiner apps"]
  node_android_app["Android app<br/>System VPN client"]
  node_android_assets["JS hooks<br/>Browser automation"]
  node_ios_proxy["iOS proxy app<br/>SOCKS client"]
  node_desktop_joiner["Desktop joiner<br/>Electron + Go"]
end

subgraph group_headless["Headless creators"]
  node_headless_vk["VK headless<br/>Go creator"]
  node_headless_telemost["Telemost headless<br/>Go creator"]
  node_headless_wbstream["WB headless<br/>Go creator"]
  node_headless_joiners["Headless joiners<br/>Joiner helpers"]
end

subgraph group_platforms["Platform adapters"]
  node_relay_dion["VK signaling<br/>VK call layer"]
  node_relay_telemost["Telemost API<br/>Telemost adapter"]
  node_relay_wbstream["WB Stream API<br/>LiveKit-backed adapter"]
  node_relay_livekit["LiveKit wire<br/>Messaging layer"]
end

node_android_app -->|"capture/proxy"| node_relay_common
node_ios_proxy -->|"SOCKS5"| node_relay_common
node_desktop_joiner -->|"join traffic"| node_relay_main
node_creator_app -->|"spawn"| node_headless_vk
node_creator_app -->|"spawn"| node_headless_telemost
node_creator_app -->|"spawn"| node_headless_wbstream
node_creator_app -->|"legacy flow"| node_hooks
node_hooks -.->|"mirror"| node_android_assets
node_android_app -->|"legacy join"| node_android_assets
node_relay_main -->|"embed payload"| node_relay_tunnel
node_relay_main -->|"WebRTC bridge"| node_relay_pion
node_relay_tunnel -->|"DC/VP8"| node_relay_pion
node_relay_pion -->|"VK"| node_relay_dion
node_relay_pion -->|"Telemost"| node_relay_telemost
node_relay_pion -->|"WB Stream"| node_relay_wbstream
node_relay_wbstream -->|"wire"| node_relay_livekit
node_headless_vk -->|"signaling"| node_relay_dion
node_headless_telemost -->|"session"| node_relay_telemost
node_headless_wbstream -->|"session"| node_relay_wbstream
node_headless_joiners -->|"join flows"| node_relay_pion
node_relay_main -.->|"mobile bindings"| node_android_app
node_relay_main -.->|"xcframework"| node_ios_proxy
node_creator_app -.->|"control/status"| node_relay_main
node_android_app -.->|"share link"| node_creator_app

click node_relay_main "https://github.com/kulikov0/whitelist-bypass/blob/main/relay/main.go"
click node_relay_common "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/common"
click node_relay_tunnel "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/tunnel"
click node_relay_pion "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/pion"
click node_relay_dion "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/dion"
click node_relay_telemost "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/telemost"
click node_relay_wbstream "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/wbstream"
click node_relay_livekit "https://github.com/kulikov0/whitelist-bypass/tree/main/relay/livekit"
click node_android_app "https://github.com/kulikov0/whitelist-bypass/tree/main/android-app/app/src/main/java/bypass/whitelist"
click node_android_assets "https://github.com/kulikov0/whitelist-bypass/tree/main/android-app/app/src/main/assets"
click node_ios_proxy "https://github.com/kulikov0/whitelist-bypass/tree/main/ios-proxy-app/whitelist-bypass-proxy"
click node_desktop_joiner "https://github.com/kulikov0/whitelist-bypass/tree/main/joiner-desktop-app"
click node_creator_app "https://github.com/kulikov0/whitelist-bypass/tree/main/creator-app"
click node_hooks "https://github.com/kulikov0/whitelist-bypass/tree/main/hooks"
click node_headless_vk "https://github.com/kulikov0/whitelist-bypass/tree/main/headless/vk"
click node_headless_telemost "https://github.com/kulikov0/whitelist-bypass/tree/main/headless/telemost"
click node_headless_wbstream "https://github.com/kulikov0/whitelist-bypass/tree/main/headless/wbstream"
click node_headless_joiners "https://github.com/kulikov0/whitelist-bypass/tree/main/headless"

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_relay_main,node_relay_common,node_relay_tunnel,node_relay_pion toneBlue
class node_creator_app,node_hooks toneAmber
class node_android_app,node_android_assets,node_ios_proxy,node_desktop_joiner toneMint
class node_headless_vk,node_headless_telemost,node_headless_wbstream,node_headless_joiners toneRose
class node_relay_dion,node_relay_telemost,node_relay_wbstream,node_relay_livekit toneIndigo
```

## Components

### Core transport

Shared Go stack that turns local proxy traffic into call-embedded tunnel payloads.

- [Relay core](https://github.com/kulikov0/whitelist-bypass/blob/main/relay/main.go): Go transport stack · Shared low-level engine for SOCKS5 proxying, tunnel framing, multiplexing, obfuscation, and mobile bindings. · `relay/main.go`
- [Common net](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/common): Proxy/runtime utils · Shared SOCKS, ICE, HTTP, status, masking, and version helpers used across the transport stack. · `relay/common`
- [Tunnel core](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/tunnel): Framing carriers · Carries multiplexed tunnel data over DataChannels or VP8 video streams. · `relay/tunnel`
- [Pion bridge](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/pion): WebRTC bindings · Pion-based signaling and platform-specific joiners for Android, iOS, and video modes. · `relay/pion`

### Creator apps

User-facing orchestration for starting calls, selecting modes, and sharing links.

- [Creator app](https://github.com/kulikov0/whitelist-bypass/tree/main/creator-app): Electron control plane · Desktop UI for selecting platform and tunnel mode, managing legacy browser flow, or spawning headless binaries. · `creator-app`
- [Browser hooks](https://github.com/kulikov0/whitelist-bypass/tree/main/hooks): Injected scripts · Legacy JS automation for creator-side browser calling flows. · `hooks`

### Joiner apps

Client-side apps that capture local traffic and feed it into the tunnel.

- [Android app](https://github.com/kulikov0/whitelist-bypass/tree/main/android-app/app/src/main/java/bypass/whitelist): System VPN client · Primary mobile joiner: VpnService capture, local proxy/tunnel service, and headless session control. · `android-app/app/src/main/java/bypass/whitelist`
- [JS hooks](https://github.com/kulikov0/whitelist-bypass/tree/main/android-app/app/src/main/assets): Browser automation · Legacy injected scripts for autoplay, joining, muting, and platform-specific DOM interactions. · `android-app/app/src/main/assets`
- [iOS proxy app](https://github.com/kulikov0/whitelist-bypass/tree/main/ios-proxy-app/whitelist-bypass-proxy): SOCKS client · Exposes a local SOCKS5 proxy backed by the shared Go mobile framework. · `ios-proxy-app/whitelist-bypass-proxy`
- [Desktop joiner](https://github.com/kulikov0/whitelist-bypass/tree/main/joiner-desktop-app): Electron + Go · Desktop joiner shell and native helper binary for desktop use cases. · `joiner-desktop-app`

### Headless creators

Go binaries that join or create calls directly without browser automation.

- [VK headless](https://github.com/kulikov0/whitelist-bypass/tree/main/headless/vk): Go creator · Headless VK creator that connects directly through platform APIs and Pion. · `headless/vk`
- [Telemost headless](https://github.com/kulikov0/whitelist-bypass/tree/main/headless/telemost): Go creator · Headless Telemost creator and tunnel relay integration. · `headless/telemost`
- [WB headless](https://github.com/kulikov0/whitelist-bypass/tree/main/headless/wbstream): Go creator · Headless WB Stream creator for direct platform API integration. · `headless/wbstream`
- [Headless joiners](https://github.com/kulikov0/whitelist-bypass/tree/main/headless): Joiner helpers · Platform-specific joiner companions for Telemost, WB Stream, and Android bridge support. · `headless`

### Platform adapters

Per-platform signaling, call control, and carrier-specific tunnel mechanics.

- [VK signaling](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/dion): VK call layer · VK-specific API, cookies, signaling, and device/call handling. · `relay/dion`
- [Telemost API](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/telemost): Telemost adapter · Telemost-specific API integration for call and relay control. · `relay/telemost`
- [WB Stream API](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/wbstream): LiveKit-backed adapter · WB Stream session and DataChannel packet handling. · `relay/wbstream`
- [LiveKit wire](https://github.com/kulikov0/whitelist-bypass/tree/main/relay/livekit): Messaging layer · Wire-format client and message handling for WB Stream integration. · `relay/livekit`

## Connections

- Android app → Common net: capture/proxy · Device traffic is converted into SOCKS5 and forwarded into the shared transport stack.
- iOS proxy app → Common net: SOCKS5 · iOS exposes a local SOCKS endpoint backed by shared Go mobile code.
- Desktop joiner → Relay core: join traffic · Desktop helper uses the shared relay stack for transport and status handling.
- Creator app → VK headless: spawn · Creator app can launch headless platform binaries.
- Creator app → Telemost headless: spawn · Creator app can launch headless platform binaries.
- Creator app → WB headless: spawn · Creator app can launch headless platform binaries.
- Creator app → Browser hooks: legacy flow · Browser automation path relies on injected scripts and tab management.
- Browser hooks → JS hooks: mirror · Android bundles equivalent legacy automation assets.
- Android app → JS hooks: legacy join · Secondary WebView-based VK fallback uses injected scripts.
- Relay core → Tunnel core: embed payload · Local proxy semantics are transformed into tunnel frames and carriers.
- Relay core → Pion bridge: WebRTC bridge · Shared stack hands off to Pion-based signaling and mobile bindings.
- Tunnel core → Pion bridge: DC/VP8 · Tunnel payloads ride over DataChannels or encoded VP8 video streams.
- Pion bridge → VK signaling: VK · Pion path connects to VK-specific call/signaling logic.
- Pion bridge → Telemost API: Telemost · Pion path connects to Telemost API integration.
- Pion bridge → WB Stream API: WB Stream · Pion path connects to WB Stream session logic.
- WB Stream API → LiveKit wire: wire · WB Stream uses LiveKit-backed messaging and wire format.
- VK headless → VK signaling: signaling · Headless VK creator attaches to the VK signaling/call layer.
- Telemost headless → Telemost API: session · Headless Telemost creator uses Telemost API and relay integration.
- WB headless → WB Stream API: session · Headless WB Stream creator uses WB Stream session mechanics.
- Headless joiners → Pion bridge: join flows · Joiner companions share the Pion-based call attachment path.
- Relay core → Android app: mobile bindings · Shared Go code is exported into Android through mobile bindings.
- Relay core → iOS proxy app: xcframework · Shared Go code is exported into iOS through the mobile framework.
- Creator app → Relay core: control/status · Desktop control plane consumes relay status and logging concepts.
- Android app → Creator app: share link · Joiner and creator UI exchange call/link state and operational status.