dm1sh/mobile_nebula

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