# trusttunnel/trusttunnelflutterclient architecture

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

- Interactive diagram: https://gitdiagram.com/trusttunnel/trusttunnelflutterclient
- Repository: https://github.com/trusttunnel/trusttunnelflutterclient

## Overview

#### 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/`.

Main entry points: [`plugins/vpn_plugin/lib/vpn_plugin.dart`](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/vpn_plugin.dart) (VPN plugin API), [`lib/data/repository/server_repository.dart`](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/repository/server_repository.dart) (Configuration repositories), [`lib/feature/app/app.dart`](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/app/app.dart) (Root app), [`lib/feature/navigation/navigation_screen.dart`](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/navigation/navigation_screen.dart) (Navigation shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flutter App"]
  node_startup(("App startup<br/>Flutter entry<br/>[main.dart]"))
  node_root_app["Root app<br/>app shell<br/>[app.dart]"]
  node_navigation["Navigation shell<br/>feature shell"]
  node_router["Routes &amp; deep links<br/>router<br/>[app_routes.dart]"]
  node_deep_link["Deep-link controller"]
  node_controller_core["Controller primitives<br/>state framework<br/>[controller.dart]"]
  node_server_config["Server configuration<br/>feature flow"]
  node_routing_config["Routing configuration<br/>feature flow"]
  node_excluded_routes["Excluded routes<br/>settings controller"]
end

subgraph group_data["Data &amp; Persistence"]
  node_repositories["Configuration repositories<br/>repository boundary"]
  node_database[("Drift database<br/>local database<br/>[app_database.dart]")]
  node_schema_migrations["Schema &amp; migrations<br/>database schema<br/>[migrations.dart]"]
  node_vpn_datasource["Native VPN datasource<br/>native datasource"]
end

subgraph group_vpn["VPN Integration"]
  node_vpn_controller["VPN lifecycle<br/>controller and scope"]
  node_vpn_plugin_api{{"VPN plugin API<br/>Flutter plugin<br/>[vpn_plugin.dart]"}}
  node_config_codec["Configuration codec<br/>plugin codec"]
  node_query_log["Query log<br/>log pipeline<br/>[log_decoder.dart]"]
end

subgraph group_native["Native Runtimes"]
  node_android_vpn{{"Android VPN<br/>Kotlin platform implementation<br/>[NativeVpnImpl.kt]"}}
  node_apple_tunnel{{"Apple packet tunnel<br/>Network Extension"}}
end

subgraph group_ops["Logs &amp; Delivery"]
  node_app_logging["Application logging<br/>sanitized local logs<br/>[app_logger.dart]"]
  node_log_export["Log export &amp; sharing<br/>export repository"]
  node_delivery["Build &amp; deployment<br/>CI workflow<br/>[deploy-apps.yml]"]
end

node_startup -->|"launches"| node_root_app
node_root_app -->|"hosts"| node_navigation
node_root_app -->|"uses"| node_router
node_deep_link -->|"converts into routes"| node_router
node_navigation -->|"opens"| node_server_config
node_navigation -->|"opens"| node_routing_config
node_controller_core -.->|"state model"| node_server_config
node_controller_core -.->|"state model"| node_vpn_controller
node_server_config -->|"reads and saves"| node_repositories
node_routing_config -->|"reads and saves"| node_repositories
node_excluded_routes -->|"persists overrides"| node_repositories
node_repositories -->|"persists configuration"| node_database
node_schema_migrations -->|"evolves schema"| node_database
node_vpn_controller -->|"controls"| node_vpn_datasource
node_vpn_datasource -->|"invokes"| node_vpn_plugin_api
node_repositories -->|"provides configuration"| node_config_codec
node_config_codec -->|"encodes for"| node_vpn_plugin_api
node_vpn_plugin_api -->|"platform channel"| node_android_vpn
node_vpn_plugin_api -->|"platform channel"| node_apple_tunnel
node_vpn_plugin_api -->|"emits VPN events"| node_query_log
node_query_log -->|"updates state"| node_vpn_controller
node_app_logging -->|"sanitized logs"| node_log_export
node_delivery -.->|"builds Android client"| node_android_vpn
node_delivery -.->|"builds Apple client"| node_apple_tunnel

click node_startup "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/main.dart"
click node_root_app "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/app/app.dart"
click node_navigation "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/navigation/navigation_screen.dart"
click node_router "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/common/router/app_routes.dart"
click node_deep_link "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/deep_link/controller/deep_link_controller.dart"
click node_controller_core "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/common/controller/controller/controller.dart"
click node_server_config "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/server/server_details/domain/service/server_details_service.dart"
click node_routing_config "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/routing/routing_details/domain/service/routing_details_service.dart"
click node_excluded_routes "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/settings/excluded_routes/controller/excluded_routes_controller.dart"
click node_repositories "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/repository/server_repository.dart"
click node_database "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/database/app_database.dart"
click node_schema_migrations "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/database/migrations/migrations.dart"
click node_vpn_datasource "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/datasources/native_sources/vpn_datasource_impl.dart"
click node_vpn_controller "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/vpn/models/vpn_controller.dart"
click node_vpn_plugin_api "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/vpn_plugin.dart"
click node_config_codec "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/domain/configuration_codec.dart"
click node_query_log "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/domain/log_decoder.dart"
click node_android_vpn "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/android/src/main/kotlin/com/adguard/trusttunnel/vpn_plugin/NativeVpnImpl.kt"
click node_apple_tunnel "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/ios/Extension/PacketTunnelProvider.swift"
click node_app_logging "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/common/logging/app_logger.dart"
click node_log_export "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/repository/export_logs_repository.dart"
click node_delivery "https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/.github/workflows/deploy-apps.yml"

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_startup,node_root_app,node_navigation,node_router,node_deep_link,node_controller_core,node_server_config,node_routing_config,node_excluded_routes toneBlue
class node_repositories,node_database,node_schema_migrations,node_vpn_datasource toneAmber
class node_vpn_controller,node_vpn_plugin_api,node_config_codec,node_query_log toneMint
class node_android_vpn,node_apple_tunnel toneRose
class node_app_logging,node_log_export,node_delivery toneIndigo
```

## Components

### Flutter App

- [App startup](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/main.dart): Flutter entry · Composes dependencies and launches the app. · `lib/main.dart`
- [Root app](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/app/app.dart): app shell · `lib/feature/app/app.dart`
- [Navigation shell](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/navigation/navigation_screen.dart): feature shell · Hosts top-level feature navigation. · `lib/feature/navigation/navigation_screen.dart`
- [Routes & deep links](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/common/router/app_routes.dart): router · `lib/common/router/app_routes.dart`
- [Deep-link controller](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/deep_link/controller/deep_link_controller.dart): controller · `lib/feature/deep_link/controller/deep_link_controller.dart`
- [Controller primitives](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/common/controller/controller/controller.dart): state framework · Provides observation and event-concurrency behavior. · `lib/common/controller/controller/controller.dart`
- [Server configuration](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/server/server_details/domain/service/server_details_service.dart): feature flow · Edits endpoints, credentials, DNS, transport, and assigned profiles. · `lib/feature/server/server_details/domain/service/server_details_service.dart`
- [Routing configuration](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/routing/routing_details/domain/service/routing_details_service.dart): feature flow · Edits destination profiles and VPN/bypass rules. · `lib/feature/routing/routing_details/domain/service/routing_details_service.dart`
- [Excluded routes](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/settings/excluded_routes/controller/excluded_routes_controller.dart): settings controller · Manages lower-level CIDR bypass overrides. · `lib/feature/settings/excluded_routes/controller/excluded_routes_controller.dart`

### Data & Persistence

- [Configuration repositories](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/repository/server_repository.dart): repository boundary · Coordinates server, routing, settings, and VPN state operations. · `lib/data/repository/server_repository.dart`
- [Drift database](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/database/app_database.dart): local database · Stores server definitions, certificates, routes, profiles, settings, and requests. · `lib/data/database/app_database.dart`
- [Schema & migrations](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/database/migrations/migrations.dart): database schema · `lib/data/database/migrations/migrations.dart`
- [Native VPN datasource](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/datasources/native_sources/vpn_datasource_impl.dart): native datasource · Isolates app data code from platform VPN access. · `lib/data/datasources/native_sources/vpn_datasource_impl.dart`

### VPN Integration

- [VPN lifecycle](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/feature/vpn/models/vpn_controller.dart): controller and scope · Drives connection state and consumes native events. · `lib/feature/vpn/models/vpn_controller.dart`
- [VPN plugin API](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/vpn_plugin.dart): Flutter plugin · Reusable GUI-independent VPN integration and configuration boundary. · `plugins/vpn_plugin/lib/vpn_plugin.dart`
- [Configuration codec](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/domain/configuration_codec.dart): plugin codec · Encodes persisted configuration into plugin models. · `plugins/vpn_plugin/lib/domain/configuration_codec.dart`
- [Query log](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/lib/domain/log_decoder.dart): log pipeline · Decodes VPN events into records for the settings UI. · `plugins/vpn_plugin/lib/domain/log_decoder.dart`

### Native Runtimes

- [Android VPN](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/plugins/vpn_plugin/android/src/main/kotlin/com/adguard/trusttunnel/vpn_plugin/NativeVpnImpl.kt): Kotlin platform implementation · `plugins/vpn_plugin/android/src/main/kotlin/com/adguard/trusttunnel/vpn_plugin/NativeVpnImpl.kt`
- [Apple packet tunnel](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/ios/Extension/PacketTunnelProvider.swift): Network Extension · iOS/macOS tunnel termination integration. · `ios/Extension/PacketTunnelProvider.swift`

### Logs & Delivery

- [Application logging](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/common/logging/app_logger.dart): sanitized local logs · Persists and sanitizes logs before display or export. · `lib/common/logging/app_logger.dart`
- [Log export & sharing](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/lib/data/repository/export_logs_repository.dart): export repository · `lib/data/repository/export_logs_repository.dart`
- [Build & deployment](https://github.com/trusttunnel/trusttunnelflutterclient/blob/master/.github/workflows/deploy-apps.yml): CI workflow · Builds and deploys Android and Apple applications. · `.github/workflows/deploy-apps.yml`

## Connections

- App startup → Root app: launches
- Root app → Navigation shell: hosts
- Root app → Routes & deep links: uses
- Deep-link controller → Routes & deep links: converts into routes
- Navigation shell → Server configuration: opens
- Navigation shell → Routing configuration: opens
- Controller primitives → Server configuration: state model
- Controller primitives → VPN lifecycle: state model
- Server configuration → Configuration repositories: reads and saves
- Routing configuration → Configuration repositories: reads and saves
- Excluded routes → Configuration repositories: persists overrides
- Configuration repositories → Drift database: persists configuration
- Schema & migrations → Drift database: evolves schema
- VPN lifecycle → Native VPN datasource: controls
- Native VPN datasource → VPN plugin API: invokes
- Configuration repositories → Configuration codec: provides configuration
- Configuration codec → VPN plugin API: encodes for
- VPN plugin API → Android VPN: platform channel
- VPN plugin API → Apple packet tunnel: platform channel
- VPN plugin API → Query log: emits VPN events
- Query log → VPN lifecycle: updates state
- Application logging → Log export & sharing: sanitized logs
- Build & deployment → Android VPN: builds Android client
- Build & deployment → Apple packet tunnel: builds Apple client