wendor/teapod-stream

Purpose and Entry Points

TeapodStream is an Android-only Flutter VPN client built around Xray protocols and Android’s TUN/VpnService interface. Flutter starts in lib/main.dart, initializes application services in lib/app.dart, and presents the client UI. Android embedding and platform-channel registration begin at android/app/src/main/kotlin/com/teapodstream/teapodstream/MainActivity.kt.

Flutter Application and State

The UI is organized as screens backed by provider-style application state. Connection state, lifecycle actions, statistics, and native VPN events are centralized in lib/providers/vpn_provider.dart; persisted configuration, profiles, settings, geo data, and subscriptions have separate providers under lib/providers/. Primary user workflows originate in lib/ui/screens/home_screen.dart, lib/ui/screens/configs_screen.dart, and lib/ui/screens/settings_screen.dart.

Profiles, Configuration, and Persistence

Protocol-neutral connection, routing, DNS, tuning, and statistics models live under lib/core/models/, especially lib/core/models/vpn_config.dart, lib/core/models/routing_config.dart, and lib/core/models/profile.dart. Storage is an explicit boundary: ordinary and secure persistence are handled by lib/core/services/config_storage_service.dart, lib/core/services/profile_storage_service.dart, and lib/core/services/storage_secure_service.dart. Migration support allows persisted data evolution through lib/core/services/storage_migration_service.dart.

Xray Configuration and Engine Boundary

Dart parses VLESS links and converts selected profiles plus runtime settings into Xray-compatible configuration. Key stages are lib/protocols/xray/vless_parser.dart, lib/protocols/xray/xray_config_builder.dart, and lib/protocols/xray/xray_engine.dart. The abstract engine contract at lib/core/interfaces/vpn_engine.dart isolates Flutter state/UI from the Android-native implementation. Xray core is supplied externally through the downloaded teapod-core AAR rather than implemented in this repository.

Native VPN Lifecycle and Traffic Path

android/app/src/main/kotlin/com/teapodstream/teapodstream/XrayVpnService.kt owns Android VpnService lifecycle, establishes the TUN interface, and coordinates the native engine. In normal mode, device traffic crosses TUN, external teapod-tun2socks, a local SOCKS5 listener, then Xray. Proxy-only mode bypasses TUN and exposes only the local SOCKS endpoint. Native event delivery crosses back to Dart via android/app/src/main/kotlin/com/teapodstream/teapodstream/VpnEventStreamHandler.kt; commands arrive through android/app/src/main/kotlin/com/teapodstream/teapodstream/VpnCommandReceiver.kt.

Native Networking, Boot, and System Integration

android/app/src/main/kotlin/com/teapodstream/teapodstream/ConnectionParams.kt carries connection parameters into the native layer. android/app/src/main/kotlin/com/teapodstream/teapodstream/PrefixTcpProxy.kt implements the Shadowsocks prefix-proxy/DPI-bypass path, with native support in android/app/src/main/cpp/vpn_helper.cpp. Reconnect, autostart, and Quick Settings controls integrate with Android through android/app/src/main/kotlin/com/teapodstream/teapodstream/BootReceiver.kt, android/app/src/main/kotlin/com/teapodstream/teapodstream/VpnServiceUtils.kt, and android/app/src/main/kotlin/com/teapodstream/teapodstream/VpnTileService.kt.

External Data and Build Runtime

The runtime depends on Android, Flutter/Dart, Java 21, Xray core, and teapod-tun2socks. build.sh downloads the binary AAR plus geoip.dat/geosite.dat, which support geo-routing configured from Flutter. Subscription retrieval and update behavior are represented by lib/core/services/subscription_service.dart and lib/core/services/update_service.dart; deep links enter through lib/core/services/deeplink_handler.dart and lib/core/services/deeplink_router.dart.