# getlantern/lantern architecture

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

- Interactive diagram: https://gitdiagram.com/getlantern/lantern
- Repository: https://github.com/getlantern/lantern

## Overview

Lantern is a cross-platform censorship-circumvention client. The main workflow is a user request through a platform client, into its VPN/tunnel implementation and the shared Go functionality that supports tunneling and related services. The tree also shows app selection, private-server, logging, update-relay, and iOS widget capabilities. Source evidence is uneven: several platform components and Go modules are indexed but not excerpted, so their unverified connections are omitted or shown as dashed.

Main entry points: [`lantern-core/core.go`](https://github.com/getlantern/lantern/blob/main/lantern-core/core.go) (Lantern core), [`android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt`](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt) (Android activity), [`android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt`](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt) (Android VPN service), [`lantern-core/mobile/mobile.go`](https://github.com/getlantern/lantern/blob/main/lantern-core/mobile/mobile.go) (Go mobile API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and controls"]
  node_android_ui["Android activity<br/>[MainActivity.kt]"]
  node_android_methods["Android methods<br/>[MethodHandler.kt]"]
  node_android_events["Android events<br/>[EventHandler.kt]"]
  node_android_status["VPN status"]
  node_tile["Quick settings tile"]
  node_widget_control["Widget tunnel control"]
  node_widget_state[("Widget state")]
  node_mac_methods["macOS methods"]
end

subgraph group_tunnel["VPN and tunnels"]
  node_android_service["Android VPN service"]
  node_android_platform["Platform interface"]
  node_go_tunnel["VPN tunnel<br/>[vpn_tunnel.go]"]
  node_ios_manager["iOS VPN manager<br/>[VPNManager.swift]"]
  node_ios_profile["VPN profile<br/>[Profile.swift]"]
  node_ios_provider["Packet tunnel provider"]
  node_mac_manager["System extension manager"]
  node_mac_vpn["macOS VPN manager<br/>[VPNManager.swift]"]
  node_mac_provider["Packet tunnel provider"]
end

subgraph group_core["Shared Go services"]
  node_go_mobile["Go mobile API<br/>[mobile.go]"]
  node_go_core["Lantern core<br/>[core.go]"]
end

subgraph group_platform["Platform features"]
  node_app_filter["App filtering<br/>[AppFilters.kt]"]
  node_go_apps["App discovery<br/>[apps.go]"]
  node_private_server["Private servers<br/>[server.go]"]
  node_update_relay["Update relay<br/>[relay.go]"]
  node_logs["Log stream<br/>[stream.go]"]
end

node_user(("User"))

node_user -.->|"requests connection"| node_android_ui
node_android_ui -->|"starts service"| node_android_service
node_android_ui -->|"registers handler"| node_android_methods
node_android_methods -->|"calls API"| node_go_mobile
node_android_service -->|"starts VPN"| node_go_mobile
node_android_service -->|"uses platform interface"| node_android_platform
node_android_service -->|"posts status"| node_android_status
node_android_ui -->|"updates status"| node_android_status
node_tile -->|"starts or stops"| node_android_service
node_android_methods -->|"uses filters"| node_app_filter
node_go_core -->|"uses tunnel"| node_go_tunnel
node_go_core -->|"uses app services"| node_go_apps
node_go_core -->|"uses server service"| node_private_server
node_ios_manager -->|"loads profile"| node_ios_profile
node_ios_manager -->|"reads connection choice"| node_widget_state
node_widget_control -->|"reads and updates"| node_widget_state
node_widget_control -.->|"starts tunnel"| node_ios_provider
node_mac_methods -->|"uses extension manager"| node_mac_manager
node_mac_vpn -.->|"starts tunnel"| node_mac_provider
node_go_mobile -.->|"delegates to core"| node_go_core
node_go_core -.->|"integrates update relay"| node_update_relay
node_android_events -.->|"delivers events"| node_android_ui
node_go_mobile -.->|"streams logs"| node_logs

click node_android_ui "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt"
click node_android_methods "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/handler/MethodHandler.kt"
click node_android_events "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/handler/EventHandler.kt"
click node_android_status "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/utils/VpnStatusManager.kt"
click node_android_service "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt"
click node_android_platform "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/PlatformInterfaceWrapper.kt"
click node_tile "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/QuickTileService.kt"
click node_app_filter "https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/apps/AppFilters.kt"
click node_go_mobile "https://github.com/getlantern/lantern/blob/main/lantern-core/mobile/mobile.go"
click node_go_core "https://github.com/getlantern/lantern/blob/main/lantern-core/core.go"
click node_go_tunnel "https://github.com/getlantern/lantern/blob/main/lantern-core/vpn_tunnel/vpn_tunnel.go"
click node_go_apps "https://github.com/getlantern/lantern/blob/main/lantern-core/apps/apps.go"
click node_private_server "https://github.com/getlantern/lantern/blob/main/lantern-core/private-server/server.go"
click node_update_relay "https://github.com/getlantern/lantern/blob/main/lantern-core/updaterelay/relay.go"
click node_logs "https://github.com/getlantern/lantern/blob/main/lantern-core/logs/stream.go"
click node_ios_manager "https://github.com/getlantern/lantern/blob/main/ios/Runner/VPN/VPNManager.swift"
click node_ios_profile "https://github.com/getlantern/lantern/blob/main/ios/Runner/VPN/Profile.swift"
click node_ios_provider "https://github.com/getlantern/lantern/blob/main/ios/Tunnel/PacketTunnelProvider.swift"
click node_widget_control "https://github.com/getlantern/lantern/blob/main/ios/LanternWidget/WidgetTunnelController.swift"
click node_widget_state "https://github.com/getlantern/lantern/blob/main/ios/Shared/VPNWidgetState.swift"
click node_mac_methods "https://github.com/getlantern/lantern/blob/main/macos/Runner/Handlers/MethodHandler.swift"
click node_mac_manager "https://github.com/getlantern/lantern/blob/main/macos/Runner/VPN/SystemExtensionManager.swift"
click node_mac_vpn "https://github.com/getlantern/lantern/blob/main/macos/Runner/VPN/VPNManager.swift"
click node_mac_provider "https://github.com/getlantern/lantern/blob/main/macos/PacketTunnel/PacketTunnelProvider.swift"

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_android_ui,node_android_methods,node_android_events,node_android_status,node_tile,node_widget_control,node_widget_state,node_mac_methods,node_user toneBlue
class node_android_service,node_android_platform,node_go_tunnel,node_ios_manager,node_ios_profile,node_ios_provider,node_mac_manager,node_mac_vpn,node_mac_provider toneAmber
class node_go_mobile,node_go_core toneMint
class node_app_filter,node_go_apps,node_private_server,node_update_relay,node_logs toneRose
```

## Components

### Client and controls

- [Android activity](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt): `android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt`
- [Android methods](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/handler/MethodHandler.kt): `android/app/src/main/kotlin/org/getlantern/lantern/handler/MethodHandler.kt`
- [Android events](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/handler/EventHandler.kt): `android/app/src/main/kotlin/org/getlantern/lantern/handler/EventHandler.kt`
- [VPN status](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/utils/VpnStatusManager.kt): `android/app/src/main/kotlin/org/getlantern/lantern/utils/VpnStatusManager.kt`
- [Quick settings tile](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/QuickTileService.kt): `android/app/src/main/kotlin/org/getlantern/lantern/service/QuickTileService.kt`
- [Widget tunnel control](https://github.com/getlantern/lantern/blob/main/ios/LanternWidget/WidgetTunnelController.swift): `ios/LanternWidget/WidgetTunnelController.swift`
- [Widget state](https://github.com/getlantern/lantern/blob/main/ios/Shared/VPNWidgetState.swift): `ios/Shared/VPNWidgetState.swift`
- [macOS methods](https://github.com/getlantern/lantern/blob/main/macos/Runner/Handlers/MethodHandler.swift): `macos/Runner/Handlers/MethodHandler.swift`

### VPN and tunnels

- [Android VPN service](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt): `android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt`
- [Platform interface](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/service/PlatformInterfaceWrapper.kt): `android/app/src/main/kotlin/org/getlantern/lantern/service/PlatformInterfaceWrapper.kt`
- [VPN tunnel](https://github.com/getlantern/lantern/blob/main/lantern-core/vpn_tunnel/vpn_tunnel.go): `lantern-core/vpn_tunnel/vpn_tunnel.go`
- [iOS VPN manager](https://github.com/getlantern/lantern/blob/main/ios/Runner/VPN/VPNManager.swift): `ios/Runner/VPN/VPNManager.swift`
- [VPN profile](https://github.com/getlantern/lantern/blob/main/ios/Runner/VPN/Profile.swift): `ios/Runner/VPN/Profile.swift`
- [Packet tunnel provider](https://github.com/getlantern/lantern/blob/main/ios/Tunnel/PacketTunnelProvider.swift): `ios/Tunnel/PacketTunnelProvider.swift`
- [System extension manager](https://github.com/getlantern/lantern/blob/main/macos/Runner/VPN/SystemExtensionManager.swift): `macos/Runner/VPN/SystemExtensionManager.swift`
- [macOS VPN manager](https://github.com/getlantern/lantern/blob/main/macos/Runner/VPN/VPNManager.swift): `macos/Runner/VPN/VPNManager.swift`
- [Packet tunnel provider](https://github.com/getlantern/lantern/blob/main/macos/PacketTunnel/PacketTunnelProvider.swift): `macos/PacketTunnel/PacketTunnelProvider.swift`

### Shared Go services

- [Go mobile API](https://github.com/getlantern/lantern/blob/main/lantern-core/mobile/mobile.go): `lantern-core/mobile/mobile.go`
- [Lantern core](https://github.com/getlantern/lantern/blob/main/lantern-core/core.go): `lantern-core/core.go`

### Platform features

- [App filtering](https://github.com/getlantern/lantern/blob/main/android/app/src/main/kotlin/org/getlantern/lantern/apps/AppFilters.kt): `android/app/src/main/kotlin/org/getlantern/lantern/apps/AppFilters.kt`
- [App discovery](https://github.com/getlantern/lantern/blob/main/lantern-core/apps/apps.go): `lantern-core/apps/apps.go`
- [Private servers](https://github.com/getlantern/lantern/blob/main/lantern-core/private-server/server.go): `lantern-core/private-server/server.go`
- [Update relay](https://github.com/getlantern/lantern/blob/main/lantern-core/updaterelay/relay.go): `lantern-core/updaterelay/relay.go`
- [Log stream](https://github.com/getlantern/lantern/blob/main/lantern-core/logs/stream.go): `lantern-core/logs/stream.go`

### Other components

- **User**

## Connections

- User → Android activity: requests connection
- Android activity → Android VPN service: starts service (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt`)
- Android activity → Android methods: registers handler (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt`)
- Android methods → Go mobile API: calls API (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/handler/MethodHandler.kt`)
- Android VPN service → Go mobile API: starts VPN (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt`)
- Android VPN service → Platform interface: uses platform interface (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt`)
- Android VPN service → VPN status: posts status (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/service/LanternVpnService.kt`)
- Android activity → VPN status: updates status (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt`)
- Quick settings tile → Android VPN service: starts or stops (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/service/QuickTileService.kt`)
- Android methods → App filtering: uses filters (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/handler/MethodHandler.kt`)
- Lantern core → VPN tunnel: uses tunnel (evidence: `lantern-core/core.go`)
- Lantern core → App discovery: uses app services (evidence: `lantern-core/core.go`)
- Lantern core → Private servers: uses server service (evidence: `lantern-core/core.go`)
- iOS VPN manager → VPN profile: loads profile (evidence: `ios/Runner/VPN/VPNManager.swift`)
- iOS VPN manager → Widget state: reads connection choice (evidence: `ios/Runner/VPN/VPNManager.swift`)
- Widget tunnel control → Widget state: reads and updates (evidence: `ios/LanternWidget/WidgetTunnelController.swift`)
- Widget tunnel control → Packet tunnel provider: starts tunnel
- macOS methods → System extension manager: uses extension manager (evidence: `macos/Runner/Handlers/MethodHandler.swift`)
- macOS VPN manager → Packet tunnel provider: starts tunnel
- Go mobile API → Lantern core: delegates to core
- Lantern core → Update relay: integrates update relay
- Android events → Android activity: delivers events (evidence: `android/app/src/main/kotlin/org/getlantern/lantern/MainActivity.kt`)
- Go mobile API → Log stream: streams logs
