# dm1sh/mobile_nebula architecture

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

- Interactive diagram: https://gitdiagram.com/dm1sh/mobile_nebula
- Repository: https://github.com/dm1sh/mobile_nebula

## Overview

#### Purpose and entry points
Mobile Nebula is a Flutter mobile client for configuring and operating Nebula VPN sites on Android and iOS. Flutter launches at `lib/main.dart`; platform hosts bridge UI actions and VPN lifecycle into native implementations through `android/app/src/main/kotlin/net/defined/mobile_nebula/MainActivity.kt` and `ios/Runner/AppDelegate.swift`.

#### Flutter application shell
The Dart layer owns navigation, user-facing site management, configuration editing, and operational views. `lib/screens/main_screen.dart` is the primary site-list/control surface; `lib/screens/site_detail_screen.dart` exposes a selected site; `lib/screens/siteConfig/site_config_screen.dart` anchors the configuration editor. Reusable models encode the configuration domain, notably `lib/models/site.dart`, `lib/models/certificate.dart`, and `lib/models/firewall_rule.dart`.

#### Site configuration and persistence flow
Users create, import/enroll, edit, and inspect site configurations via the enrollment and site-config screens: `lib/screens/enrollment_screen.dart`, `lib/screens/siteConfig/rendered_config_screen.dart`, and `lib/screens/siteConfig/scan_qr_screen.dart`. Dart storage/settings services persist app and site state, while native migration code maintains platform-compatible configuration formats: `lib/services/storage.dart`, `android/app/src/main/kotlin/net/defined/mobile_nebula/ConfigMigrator.kt`, and `ios/NebulaNetworkExtension/ConfigMigrator.swift`.

#### Native VPN boundary
Dart does not directly implement packet tunneling. Android runs the tunnel through an Android `VpnService` in `android/app/src/main/kotlin/net/defined/mobile_nebula/NebulaVpnService.kt`; iOS uses a Packet Tunnel network extension in `ios/NebulaNetworkExtension/PacketTunnelProvider.swift`. Native site representations coordinate configuration and lifecycle on each platform: `android/app/src/main/kotlin/net/defined/mobile_nebula/Sites.kt`, `ios/NebulaNetworkExtension/Site.swift`, and `ios/NebulaNetworkExtension/SiteList.swift`. This boundary is subject to platform VPN permissions, entitlements, and extension process constraints.

#### Embedded Nebula engine
The VPN protocol/control implementation is Go code compiled for mobile consumption with `gomobile`. Its mobile-facing API and tunnel control surface are in `nebula/mobileNebula.go`, `nebula/api.go`, and `nebula/control.go`; configuration/site translation is in `nebula/config.go` and `nebula/site.go`. Native Android and iOS code consume the generated mobile artifact, separating protocol execution from Flutter UI and platform VPN APIs.

#### Platform integration and external interactions
Platform API clients support enrollment or remote service interactions through `android/app/src/main/kotlin/net/defined/mobile_nebula/APIClient.kt` and `ios/Runner/APIClient.swift`. DNS/update behavior is platform-specific, with Android background update work in `android/app/src/main/kotlin/net/defined/mobile_nebula/DNUpdateWorker.kt` and iOS update integration in `ios/Runner/DNUpdate.swift`. iOS secure credential handling is explicitly isolated in `ios/NebulaNetworkExtension/Keychain.swift`.

#### Build and delivery
The repository requires Flutter, Go/gomobile, Android NDK/Gradle, and Xcode/CocoaPods. Android packaging is defined under `android/app/build.gradle.kts`; iOS app and network-extension wiring lives in `ios/Runner.xcodeproj/project.pbxproj` and `ios/NebulaNetworkExtension/Info.plist`. Fastlane directories (`android/fastlane/Fastfile`, `ios/fastlane/Fastfile`) support store release workflows, with CI under `.github/workflows/`.

Main entry points: [`lib/screens/main_screen.dart`](https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/main_screen.dart) (Site management UI), [`android/app/src/main/kotlin/net/defined/mobile_nebula/Sites.kt`](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/Sites.kt) (Android site manager), [`ios/NebulaNetworkExtension/SiteList.swift`](https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/SiteList.swift) (iOS site manager), [`lib/screens/siteConfig/site_config_screen.dart`](https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/siteConfig/site_config_screen.dart) (Configuration editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_flutter_entry["Flutter entry<br/>Dart entrypoint<br/>[main.dart]"]
  node_app_shell["Site management UI<br/>Flutter screens<br/>[main_screen.dart]"]
  node_site_detail["Site detail<br/>Flutter screen"]
  node_config_editor["Configuration editor<br/>Flutter screens"]
  node_config_models["Configuration domain<br/>Dart models<br/>[site.dart]"]
  node_storage[("App &amp; site storage<br/>Dart service<br/>[storage.dart]")]
end

subgraph group_android["Android"]
  node_android_host["Android host bridge<br/>Flutter activity<br/>[MainActivity.kt]"]
  node_android_sites["Android site manager<br/>native sites<br/>[Sites.kt]"]
  node_android_vpn{{"Android tunnel service<br/>VpnService"}}
  node_android_migration["Android config migration<br/>native migration<br/>[ConfigMigrator.kt]"]
  node_android_remote["Android remote updates<br/>API and worker<br/>[APIClient.kt]"]
end

subgraph group_ios["iOS"]
  node_ios_host["iOS host bridge<br/>Flutter app delegate<br/>[AppDelegate.swift]"]
  node_ios_sites["iOS site manager<br/>extension sites<br/>[SiteList.swift]"]
  node_ios_tunnel{{"iOS packet tunnel<br/>network extension"}}
  node_ios_secure_config["iOS secure configuration<br/>migration &amp; keychain"]
  node_ios_remote["iOS remote updates<br/>API and update integration<br/>[APIClient.swift]"]
end

subgraph group_engine["Nebula engine"]
  node_mobile_api["Mobile tunnel API<br/>Go mobile API<br/>[mobileNebula.go]"]
  node_nebula_config["Engine site translation<br/>Go configuration<br/>[config.go]"]
  node_nebula_engine{{"Nebula protocol engine<br/>Go VPN engine<br/>[control.go]"}}
end

subgraph group_delivery["Build &amp; delivery"]
  node_android_build["Android package build<br/>Gradle/NDK build<br/>[build.gradle.kts]"]
  node_ios_build["iOS app &amp; extension build<br/>Xcode build<br/>[project.pbxproj]"]
  node_release["Store release automation<br/>Fastlane"]
end

node_flutter_entry -->|"starts"| node_app_shell
node_app_shell -->|"opens"| node_site_detail
node_app_shell -->|"creates and edits"| node_config_editor
node_site_detail -->|"edits"| node_config_editor
node_config_editor -->|"reads and writes"| node_config_models
node_config_models -->|"persists"| node_storage
node_app_shell -.->|"Android actions"| node_android_host
node_app_shell -.->|"iOS actions"| node_ios_host
node_android_host -->|"manages"| node_android_sites
node_android_sites -->|"migrates config"| node_android_migration
node_android_sites -->|"starts and stops"| node_android_vpn
node_android_vpn -->|"consumes generated artifact"| node_mobile_api
node_ios_host -->|"manages"| node_ios_sites
node_ios_sites -->|"migrates and secures"| node_ios_secure_config
node_ios_sites -->|"configures"| node_ios_tunnel
node_ios_tunnel -->|"consumes generated artifact"| node_mobile_api
node_mobile_api -->|"translates configuration"| node_nebula_config
node_nebula_config -->|"configures"| node_nebula_engine
node_android_remote -->|"enrollment and updates"| node_android_sites
node_ios_remote -->|"enrollment and updates"| node_ios_sites
node_android_build -.->|"packages"| node_android_vpn
node_ios_build -.->|"packages extension"| node_ios_tunnel
node_release -.->|"releases"| node_android_build

click node_flutter_entry "https://github.com/dm1sh/mobile_nebula/blob/main/lib/main.dart"
click node_app_shell "https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/main_screen.dart"
click node_site_detail "https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/site_detail_screen.dart"
click node_config_editor "https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/siteConfig/site_config_screen.dart"
click node_config_models "https://github.com/dm1sh/mobile_nebula/blob/main/lib/models/site.dart"
click node_storage "https://github.com/dm1sh/mobile_nebula/blob/main/lib/services/storage.dart"
click node_android_host "https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/MainActivity.kt"
click node_android_sites "https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/Sites.kt"
click node_android_vpn "https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/NebulaVpnService.kt"
click node_android_migration "https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/ConfigMigrator.kt"
click node_android_remote "https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/APIClient.kt"
click node_ios_host "https://github.com/dm1sh/mobile_nebula/blob/main/ios/Runner/AppDelegate.swift"
click node_ios_sites "https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/SiteList.swift"
click node_ios_tunnel "https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/PacketTunnelProvider.swift"
click node_ios_secure_config "https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/ConfigMigrator.swift"
click node_ios_remote "https://github.com/dm1sh/mobile_nebula/blob/main/ios/Runner/APIClient.swift"
click node_mobile_api "https://github.com/dm1sh/mobile_nebula/blob/main/nebula/mobileNebula.go"
click node_nebula_config "https://github.com/dm1sh/mobile_nebula/blob/main/nebula/config.go"
click node_nebula_engine "https://github.com/dm1sh/mobile_nebula/blob/main/nebula/control.go"
click node_android_build "https://github.com/dm1sh/mobile_nebula/blob/main/android/app/build.gradle.kts"
click node_ios_build "https://github.com/dm1sh/mobile_nebula/blob/main/ios/Runner.xcodeproj/project.pbxproj"
click node_release "https://github.com/dm1sh/mobile_nebula/blob/main/android/fastlane/Fastfile"

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_flutter_entry,node_app_shell,node_site_detail,node_config_editor,node_config_models,node_storage toneBlue
class node_android_host,node_android_sites,node_android_vpn,node_android_migration,node_android_remote toneAmber
class node_ios_host,node_ios_sites,node_ios_tunnel,node_ios_secure_config,node_ios_remote toneMint
class node_mobile_api,node_nebula_config,node_nebula_engine toneRose
class node_android_build,node_ios_build,node_release toneIndigo
```

## Components

### Flutter app

- [Flutter entry](https://github.com/dm1sh/mobile_nebula/blob/main/lib/main.dart): Dart entrypoint · `lib/main.dart`
- [Site management UI](https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/main_screen.dart): Flutter screens · Primary site list and control surface. · `lib/screens/main_screen.dart`
- [Site detail](https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/site_detail_screen.dart): Flutter screen · `lib/screens/site_detail_screen.dart`
- [Configuration editor](https://github.com/dm1sh/mobile_nebula/blob/main/lib/screens/siteConfig/site_config_screen.dart): Flutter screens · Editing, rendered configuration, enrollment, and QR import flows. · `lib/screens/siteConfig/site_config_screen.dart`
- [Configuration domain](https://github.com/dm1sh/mobile_nebula/blob/main/lib/models/site.dart): Dart models · Site, certificate, and firewall-rule representations. · `lib/models/site.dart`
- [App & site storage](https://github.com/dm1sh/mobile_nebula/blob/main/lib/services/storage.dart): Dart service · `lib/services/storage.dart`

### Android

- [Android host bridge](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/MainActivity.kt): Flutter activity · Bridges Flutter actions into Android VPN lifecycle. · `android/app/src/main/kotlin/net/defined/mobile_nebula/MainActivity.kt`
- [Android site manager](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/Sites.kt): native sites · `android/app/src/main/kotlin/net/defined/mobile_nebula/Sites.kt`
- [Android tunnel service](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/NebulaVpnService.kt): VpnService · Runs the tunnel under Android VPN permissions. · `android/app/src/main/kotlin/net/defined/mobile_nebula/NebulaVpnService.kt`
- [Android config migration](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/ConfigMigrator.kt): native migration · `android/app/src/main/kotlin/net/defined/mobile_nebula/ConfigMigrator.kt`
- [Android remote updates](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/src/main/kotlin/net/defined/mobile_nebula/APIClient.kt): API and worker · Enrollment API client and background DNS/update work. · `android/app/src/main/kotlin/net/defined/mobile_nebula/APIClient.kt`

### iOS

- [iOS host bridge](https://github.com/dm1sh/mobile_nebula/blob/main/ios/Runner/AppDelegate.swift): Flutter app delegate · Bridges Flutter actions into iOS application services. · `ios/Runner/AppDelegate.swift`
- [iOS site manager](https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/SiteList.swift): extension sites · Site and site-list lifecycle representation. · `ios/NebulaNetworkExtension/SiteList.swift`
- [iOS packet tunnel](https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/PacketTunnelProvider.swift): network extension · Tunnel process constrained by iOS VPN entitlements and extension lifecycle. · `ios/NebulaNetworkExtension/PacketTunnelProvider.swift`
- [iOS secure configuration](https://github.com/dm1sh/mobile_nebula/blob/main/ios/NebulaNetworkExtension/ConfigMigrator.swift): migration & keychain · Migrates configuration and isolates credentials in the extension. · `ios/NebulaNetworkExtension/ConfigMigrator.swift`
- [iOS remote updates](https://github.com/dm1sh/mobile_nebula/blob/main/ios/Runner/APIClient.swift): API and update integration · `ios/Runner/APIClient.swift`

### Nebula engine

- [Mobile tunnel API](https://github.com/dm1sh/mobile_nebula/blob/main/nebula/mobileNebula.go): Go mobile API · gomobile-facing API and tunnel control surface. · `nebula/mobileNebula.go`
- [Engine site translation](https://github.com/dm1sh/mobile_nebula/blob/main/nebula/config.go): Go configuration · Translates mobile configuration into engine site state. · `nebula/config.go`
- [Nebula protocol engine](https://github.com/dm1sh/mobile_nebula/blob/main/nebula/control.go): Go VPN engine · Embedded VPN protocol and control execution. · `nebula/control.go`

### Build & delivery

- [Android package build](https://github.com/dm1sh/mobile_nebula/blob/main/android/app/build.gradle.kts): Gradle/NDK build · Packages the Flutter app, native VPN service, and mobile engine artifact. · `android/app/build.gradle.kts`
- [iOS app & extension build](https://github.com/dm1sh/mobile_nebula/blob/main/ios/Runner.xcodeproj/project.pbxproj): Xcode build · Wires the app and Packet Tunnel extension. · `ios/Runner.xcodeproj/project.pbxproj`
- [Store release automation](https://github.com/dm1sh/mobile_nebula/blob/main/android/fastlane/Fastfile): Fastlane · `android/fastlane/Fastfile`

## Connections

- Flutter entry → Site management UI: starts
- Site management UI → Site detail: opens
- Site management UI → Configuration editor: creates and edits
- Site detail → Configuration editor: edits
- Configuration editor → Configuration domain: reads and writes
- Configuration domain → App & site storage: persists
- Site management UI → Android host bridge: Android actions
- Site management UI → iOS host bridge: iOS actions
- Android host bridge → Android site manager: manages
- Android site manager → Android config migration: migrates config
- Android site manager → Android tunnel service: starts and stops
- Android tunnel service → Mobile tunnel API: consumes generated artifact
- iOS host bridge → iOS site manager: manages
- iOS site manager → iOS secure configuration: migrates and secures
- iOS site manager → iOS packet tunnel: configures
- iOS packet tunnel → Mobile tunnel API: consumes generated artifact
- Mobile tunnel API → Engine site translation: translates configuration
- Engine site translation → Nebula protocol engine: configures
- Android remote updates → Android site manager: enrollment and updates
- iOS remote updates → iOS site manager: enrollment and updates
- Android package build → Android tunnel service: packages
- iOS app & extension build → iOS packet tunnel: packages extension
- Store release automation → Android package build: releases