trusttunnel/trusttunnelflutterclient

Purpose and Entry Points

TrustTunnel Flutter Client is a Flutter GUI for configuring and operating connections to self-hosted TrustTunnel VPN servers. It manages server credentials/endpoints, routing behavior, VPN lifecycle, and query logs; the server remains responsible for authentication and tunnel termination.

Application startup is lib/main.dart, which composes dependencies and launches the root app at lib/feature/app/app.dart. Native Flutter host entry points exist for Android (android/app/src/main/kotlin/com/adguard/trusttunnel/MainActivity.kt) and Apple platforms (ios/Runner/AppDelegate.swift, macos/Runner/AppDelegate.swift).

App Composition, State, and Navigation

The UI is organized as feature modules backed by controllers, explicit state classes, scoped widgets, and domain services. Shared controller primitives define state observation and event-concurrency behavior under lib/common/controller/controller/controller.dart and lib/common/controller/concurrency/.

Navigation is centralized through route definitions and deep-link conversion in lib/common/router/app_routes.dart, lib/common/router/deeplink/deep_link_converter.dart, and the top-level shell lib/feature/navigation/navigation_screen.dart. Deep links enter through the plugin boundary and are handled by lib/feature/deep_link/controller/deep_link_controller.dart.

Persistent Configuration and Repository Boundary

The data layer owns local persistence and shields features from database/native details. Drift database setup, schema evolution, and tables are in lib/data/database/app_database.dart, lib/data/database/migrations/migrations.dart, and lib/data/database/tables/index.drift.

Repositories coordinate feature-facing operations for servers, routing, settings, and VPN state: lib/data/repository/server_repository.dart, lib/data/repository/routing_repository.dart, and lib/data/repository/vpn_repository.dart. Local datasource implementations persist server definitions, certificates, routes, profiles, settings, and VPN requests; native VPN access is isolated at lib/data/datasources/native_sources/vpn_datasource_impl.dart.

Server and Routing Configuration Flow

Users create/edit server definitions, including endpoint, credentials, DNS, transport protocol, and assigned routing profile. This flow is implemented through server list/detail controllers and services: lib/feature/server/servers/controller/servers_controller.dart, lib/feature/server/server_details/domain/service/server_details_service.dart, and lib/feature/server/server_details/widgets/server_details_form.dart.

Routing profiles model client-side destination rules and VPN-versus-bypass mode, while excluded CIDR routes are a separate lower-level override. Profile editing is centered on lib/feature/routing/routing_details/domain/service/routing_details_service.dart; excluded routes use lib/feature/settings/excluded_routes/controller/excluded_routes_controller.dart. Persisted configuration is encoded into VPN-plugin models before connection.

VPN Execution Boundary

plugins/vpn_plugin is the reusable, GUI-independent VPN integration layer. Flutter-facing API and configuration encoding live in plugins/vpn_plugin/lib/vpn_plugin.dart, plugins/vpn_plugin/lib/domain/configuration_codec.dart, and plugins/vpn_plugin/pigeons/platform_api.dart.

The app’s VPN controller/scope drives lifecycle state and reacts to native events via lib/feature/vpn/models/vpn_controller.dart, lib/feature/vpn/widgets/vpn_scope.dart, and lib/data/datasources/native_sources/vpn_datasource_impl.dart. Native implementations integrate with platform VPN facilities: Android (plugins/vpn_plugin/android/src/main/kotlin/com/adguard/trusttunnel/vpn_plugin/NativeVpnImpl.kt) and Apple Network Extension packet tunnels (ios/Extension/PacketTunnelProvider.swift, macos/Extension/PacketTunnelProvider.swift). Linux and Windows plugin shells also exist, but mobile Apple/Android VPN support is architecturally primary.

Observability and Log Export

VPN events are decoded into query-log records by the plugin (plugins/vpn_plugin/lib/domain/log_decoder.dart) and surfaced by the app’s VPN/log models (lib/feature/vpn/domain/services/vpn_log_converter.dart, lib/data/model/vpn_log.dart). Query-log UI reads this stream under lib/feature/settings/query_log/widgets/query_log_screen.dart.

Application logging is persisted and sanitized before display/export, with central facilities in lib/common/logging/app_logger.dart, lib/common/logging/sanitizer/trust_tunnel_sensitive_data_sanitizer.dart, and lib/data/datasources/local_sources/logs_local_source_impl.dart. Export and sharing flow through lib/data/repository/export_logs_repository.dart and the local native-share package packages/adg_share/lib/adg_share.dart.

Runtime and Delivery

The primary runtime is Flutter/Dart, with Kotlin Android code and Swift iOS/macOS code. Android builds resolve private GitHub Packages artifacts; deployment/build workflows are defined in .github/workflows/deploy-apps.yml, .github/workflows/flutter-build-android.yml, and .github/workflows/flutter-build-ios.yml. Apple builds use CocoaPods, Fastlane, signing, and Network Extension entitlements under ios/ and macos/.