# guardianproject/orbot-android architecture

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

- Interactive diagram: https://gitdiagram.com/guardianproject/orbot-android
- Repository: https://github.com/guardianproject/orbot-android

## Overview

1. **What this repo is**
   Orbot is an Android app that turns the device into a Tor-powered proxy/VPN client. Its core job is to start and supervise Tor, route selected app traffic through it, and provide a UI for connection, bridge, onion-service, and privacy settings.

2. **Top-level runtime boundaries**
   There are two important execution domains: the main Android app process and a separate `:tor` process for Tor itself. The readme notes that Tor now runs as its own Linux process, which cleanly separates UI/service logic from the actual Tor daemon logs and lifecycle.

3. **User-facing application layer**
   `OrbotActivity`, `BaseActivity`, and the fragments under `ui/` form the main interaction surface. The app uses a bottom-navigation style UI with major sections such as Connect, App Manager, Kindness, and More. Navigation and screen layout are defined in `res/navigation` and `res/layout*`.

4. **Connection management subsystem**
   The `ui/connect` package is the main control panel for starting/stopping the Tor connection, choosing how to connect, selecting bridges, and handling permission prompts. `ConnectViewModel` and `ConnectUiState` suggest a state-driven UI layer that reflects service status, logs, and connection setup results.

5. **Tor service orchestration**
   The `service` package is the backend coordinator. `OrbotService`, `StartTorReceiver`, `OnBootReceiver`, and `Notifications` manage startup, restarts, boot handling, foreground-service behavior, and ongoing status notifications. `OrbotConstants` centralizes service-wide config and intent/action names.

6. **Traffic routing and VPN boundary**
   The VPN path is implemented under `service/vpn` with `OrbotVpnManager`, `VpnServicePrepareWrapper`, and `TorifiedApp`/`TorifiedAppWrapper`. This subsystem decides which apps are “torified” and likely controls Android VPN routing so selected app traffic goes through Tor rather than the normal network stack.

7. **Native tunnel and low-level networking**
   The repo includes native code under `app/src/main/jni/hev-socks5-tunnel` and prebuilt libraries in `jniLibs`. This indicates a lower-level SOCKS5/tunneling layer used to bridge Android networking to Tor or to support VPN transport. `ShadowSocks.kt`, `TProxyService.kt`, and `TorConfig.kt` are the main Java/Kotlin pieces around this networking stack.

8. **Circumvention and bridge acquisition**
   The `service/circumvention` package handles blocked-network resilience. It includes `Bridge`, `BuiltInBridges`, `Transport`, `SmartConnect`, `AutoConf`, `MoatApi`, and `MoatTunnel`, which together suggest: built-in bridge catalogs, transport selection, automatic configuration, and bridge retrieval through Moat. Assets like `builtin-bridges.json`, `fronts`, and country-specific `dns-*.json` files are part of this subsystem’s offline/region-aware data.

9. **Kindness / snowflake proxy mode**
   The `ui/kindness` package implements a separate feature for running a Snowflake proxy, likely to help other users reach Tor. `SnowflakeProxyService`, `SnowflakeProxyWrapper`, `PowerConnectionReceiver`, and related dialogs indicate a power/network-state-sensitive background service with user controls and test flows. This is a distinct subsystem from normal client connection mode.

10. **Onion service and client authorization management**
   The `ui/v3onionservice` area manages hosting Tor onion services and their backups/restores. A parallel `clientauth` package handles v3 client authorization data. These subsystems include their own activities, dialogs, content providers, databases, list adapters, and backup utilities, showing that local persistence and CRUD-style management are important here.

11. **Local data and persistence**
   The repo contains database/schema classes for onion services and client auth, plus preference helpers in `util/Prefs.kt` and `util/PreferenceProvider.kt`. This suggests three main state stores: Android shared preferences for app settings, app-local databases for onion-service/auth records, and files/assets for bundled bridge and localization data.

12. **System integration points**
   The app integrates with Android boot broadcast handling, quick settings tiles (`ui/quicksettings`), notifications, device authentication prompts, exact alarm permission handling, and battery optimization prompts. These are the main OS-facing boundaries where Orbot asks for privileges or exposes control outside the app UI.

13. **Localization and regional behavior**
   `localization/` plus `Regionalization.kt` and many `res/values-*` folders show heavy locale support. The assets `dns-*.json` and bridge/front data also imply region-aware behavior, likely used to adapt connection strategies for censored or restrictive environments.

14. **Build, release, and external dependencies**
   The project is a Gradle-based Android build with Kotlin/Java plus native code, CI workflows, and Fastlane metadata/screenshots for store release. External runtime dependencies that materially affect architecture are Tor itself, the `hev-socks5-tunnel` native dependency, Moat/bridge discovery services, and the Android VPN/foreground-service APIs.

15. **How data flows through the system**
   A typical flow is: user action in the UI → ViewModel/state update → service intent/receiver → Tor startup and network configuration → VPN/tunnel setup and optional bridge acquisition → live status/log updates back to the UI via notifications/state. Separate flows exist for onion-service CRUD and for Snowflake proxy operation, but they share the same Android app shell and persistence infrastructure.

Main entry points: [`app/src/main/java/org/torproject/android/service/OrbotService.java`](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/OrbotService.java) (Orbot Service), [`app/src/main/res/navigation/nav_graph.xml`](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/res/navigation/nav_graph.xml) (Navigation), [`app/src/main/java/org/torproject/android/ui/connect/ConnectFragment.kt`](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectFragment.kt) (Connect), [`app/src/main/java/org/torproject/android/service/vpn/OrbotVpnManager.java`](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/vpn/OrbotVpnManager.java) (VPN)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App Shell"]
  node_n_orbot_activity["Orbot<br/>android activity<br/>[OrbotActivity.kt]"]
  node_n_base_activity["Base UI<br/>activity base<br/>[BaseActivity.kt]"]
  node_n_nav["Navigation<br/>[nav_graph.xml]"]
  node_n_connect_frag["Connect<br/>ui fragment<br/>[ConnectFragment.kt]"]
  node_n_connect_vm["Connect VM<br/>state viewmodel"]
  node_n_connect_state["Connect State<br/>ui state<br/>[ConnectUiState.kt]"]
  node_n_app_manager["App Manager<br/>ui fragment"]
  node_n_more_frag["More<br/>ui fragment<br/>[MoreFragment.kt]"]
end

subgraph group_g_service["Tor Service"]
  node_n_orbot_service[("Orbot Service<br/>android service<br/>[OrbotService.java]")]
  node_n_boot_start["Startup<br/>receivers"]
  node_n_notifications["Notifications<br/>service ui<br/>[Notifications.kt]"]
end

subgraph group_g_network["Networking"]
  node_n_vpn_mgr[("VPN")]
  node_n_torified["Torified Apps<br/>vpn policy<br/>[TorifiedApp.kt]"]
  node_n_tproxy[("Tunnel<br/>network bridge<br/>[TProxyService.kt]")]
  node_n_tor_config["Tor Config<br/>[TorConfig.kt]"]
end

subgraph group_g_circ["Circumvention"]
  node_n_circumvention{{"Bridges<br/>circumvention<br/>[SmartConnect.kt]"}}
  node_n_assets["Bridge Data<br/>assets"]
end

subgraph group_g_onion["Onion Services"]
  node_n_onion["Onion Services<br/>onion hosting"]
  node_n_clientauth["Client Auth<br/>onion auth"]
end

subgraph group_g_kindness["Kindness Mode"]
  node_n_kindness["Kindness<br/>snowflake ui"]
  node_n_snowflake[("Snowflake Proxy<br/>background service")]
end

node_n_orbot_activity -->|"hosts sections"| node_n_nav
node_n_orbot_activity -->|"extends"| node_n_base_activity
node_n_nav -->|"routes to"| node_n_connect_frag
node_n_nav -->|"routes to"| node_n_app_manager
node_n_nav -->|"routes to"| node_n_more_frag
node_n_connect_frag -->|"observes"| node_n_connect_vm
node_n_connect_vm -->|"emits"| node_n_connect_state
node_n_connect_frag -->|"starts/stops"| node_n_orbot_service
node_n_boot_start -->|"launches"| node_n_orbot_service
node_n_orbot_service -->|"publishes status"| node_n_notifications
node_n_orbot_service -->|"configures Tor"| node_n_tor_config
node_n_orbot_service -->|"controls"| node_n_vpn_mgr
node_n_vpn_mgr -->|"applies policy"| node_n_torified
node_n_vpn_mgr -->|"routes traffic"| node_n_tproxy
node_n_tproxy -->|"binds to"| node_n_tor_config
node_n_connect_frag -->|"selects bridges"| node_n_circumvention
node_n_circumvention -->|"loads data"| node_n_assets
node_n_kindness -->|"controls"| node_n_snowflake
node_n_snowflake -.->|"shares runtime"| node_n_orbot_service
node_n_onion -->|"manages auth"| node_n_clientauth
node_n_onion -.->|"uses backend"| node_n_orbot_service
node_n_more_frag -.->|"reads logs/status"| node_n_notifications

click node_n_orbot_activity "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/OrbotActivity.kt"
click node_n_base_activity "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/core/BaseActivity.kt"
click node_n_nav "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/res/navigation/nav_graph.xml"
click node_n_connect_frag "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectFragment.kt"
click node_n_connect_vm "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectViewModel.kt"
click node_n_connect_state "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectUiState.kt"
click node_n_app_manager "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/AppManagerFragment.kt"
click node_n_more_frag "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/more/MoreFragment.kt"
click node_n_orbot_service "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/OrbotService.java"
click node_n_boot_start "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/StartTorReceiver.kt"
click node_n_notifications "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/Notifications.kt"
click node_n_vpn_mgr "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/vpn/OrbotVpnManager.java"
click node_n_torified "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/vpn/TorifiedApp.kt"
click node_n_tproxy "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/TProxyService.kt"
click node_n_tor_config "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/tor/TorConfig.kt"
click node_n_circumvention "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/circumvention/SmartConnect.kt"
click node_n_assets "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/assets/builtin-bridges.json"
click node_n_kindness "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/kindness/KindnessFragment.kt"
click node_n_snowflake "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/kindness/SnowflakeProxyService.kt"
click node_n_onion "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/v3onionservice/OnionServiceActivity.java"
click node_n_clientauth "https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/v3onionservice/clientauth/ClientAuthActivity.java"

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_n_orbot_activity,node_n_base_activity,node_n_nav,node_n_connect_frag,node_n_connect_vm,node_n_connect_state,node_n_app_manager,node_n_more_frag toneBlue
class node_n_orbot_service,node_n_boot_start,node_n_notifications toneAmber
class node_n_vpn_mgr,node_n_torified,node_n_tproxy,node_n_tor_config toneMint
class node_n_circumvention,node_n_assets toneRose
class node_n_onion,node_n_clientauth toneIndigo
class node_n_kindness,node_n_snowflake toneTeal
```

## Components

### App Shell

Main Android process, lifecycle entrypoints, navigation, and shared UI scaffolding.

- [Orbot](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/OrbotActivity.kt): android activity · Main app entrypoint and user-facing shell. · `app/src/main/java/org/torproject/android/OrbotActivity.kt`
- [Base UI](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/core/BaseActivity.kt): activity base · Shared activity behavior and common UI plumbing. · `app/src/main/java/org/torproject/android/ui/core/BaseActivity.kt`
- [Navigation](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/res/navigation/nav_graph.xml): android navigation · Screen graph and layout resources for app sections. · `app/src/main/res/navigation/nav_graph.xml`
- [Connect](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectFragment.kt): ui fragment · Main connection control surface for Tor startup and bridges. · `app/src/main/java/org/torproject/android/ui/connect/ConnectFragment.kt`
- [Connect VM](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectViewModel.kt): state viewmodel · State holder for connection status, setup, and log-driven UI. · `app/src/main/java/org/torproject/android/ui/connect/ConnectViewModel.kt`
- [Connect State](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/connect/ConnectUiState.kt): ui state · Structured connection state rendered by the connect screen. · `app/src/main/java/org/torproject/android/ui/connect/ConnectUiState.kt`
- [App Manager](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/AppManagerFragment.kt): ui fragment · Controls which apps are routed through Tor. · `app/src/main/java/org/torproject/android/ui/AppManagerFragment.kt`
- [More](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/more/MoreFragment.kt): ui fragment · Settings, logs, safety, and miscellaneous app controls. · `app/src/main/java/org/torproject/android/ui/more/MoreFragment.kt`

### Tor Service

Process orchestration, startup, notifications, boot handling, and Tor lifecycle control.

- [Orbot Service](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/OrbotService.java): android service · Central backend that supervises Tor and app networking. · `app/src/main/java/org/torproject/android/service/OrbotService.java`
- [Startup](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/StartTorReceiver.kt): receivers · Boot and explicit-start receivers that wake the service. · `app/src/main/java/org/torproject/android/service/StartTorReceiver.kt`
- [Notifications](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/Notifications.kt): service ui · Foreground and status notifications for connection lifecycle. · `app/src/main/java/org/torproject/android/service/Notifications.kt`

### Networking

VPN, Tor routing, and low-level tunnel integration.

- [VPN](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/vpn/OrbotVpnManager.java): vpn manager · Prepares and manages Android VPN routing for torified apps. · `app/src/main/java/org/torproject/android/service/vpn/OrbotVpnManager.java`
- [Torified Apps](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/vpn/TorifiedApp.kt): vpn policy · App allowlist/torification model used by the VPN layer. · `app/src/main/java/org/torproject/android/service/vpn/TorifiedApp.kt`
- [Tunnel](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/TProxyService.kt): network bridge · Low-level SOCKS/tproxy bridge between Android networking and Tor. · `app/src/main/java/org/torproject/android/service/TProxyService.kt`
- [Tor Config](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/tor/TorConfig.kt): tor config · Tor configuration and resource installation for runtime startup. · `app/src/main/java/org/torproject/android/service/tor/TorConfig.kt`

### Circumvention

Bridge discovery, auto-configuration, and restricted-network connection strategies.

- [Bridges](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/service/circumvention/SmartConnect.kt): circumvention · Bridge catalog, transport selection, auto-configuration, and Moat retrieval. · `app/src/main/java/org/torproject/android/service/circumvention/SmartConnect.kt`
- [Bridge Data](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/assets/builtin-bridges.json): assets · Bundled bridge lists and region-specific DNS/front data. · `app/src/main/assets/builtin-bridges.json`

### Onion Services

Onion service hosting and client authorization management.

- [Onion Services](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/v3onionservice/OnionServiceActivity.java): onion hosting · Hosting and managing v3 onion services with local persistence. · `app/src/main/java/org/torproject/android/ui/v3onionservice/OnionServiceActivity.java`
- [Client Auth](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/v3onionservice/clientauth/ClientAuthActivity.java): onion auth · v3 client authorization CRUD and backup flows. · `app/src/main/java/org/torproject/android/ui/v3onionservice/clientauth/ClientAuthActivity.java`

### Kindness Mode

Snowflake proxy features and related background controls.

- [Kindness](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/kindness/KindnessFragment.kt): snowflake ui · Snowflake proxy mode for helping others reach Tor. · `app/src/main/java/org/torproject/android/ui/kindness/KindnessFragment.kt`
- [Snowflake Proxy](https://github.com/guardianproject/orbot-android/blob/master/app/src/main/java/org/torproject/android/ui/kindness/SnowflakeProxyService.kt): background service · Service and wrapper for running the Snowflake proxy. · `app/src/main/java/org/torproject/android/ui/kindness/SnowflakeProxyService.kt`

## Connections

- Orbot → Navigation: hosts sections · Main activity renders the bottom-navigation app shell.
- Orbot → Base UI: extends · Shared activity behavior comes from the base class.
- Navigation → Connect: routes to · Navigation graph opens the connection control screen.
- Navigation → App Manager: routes to · Navigation graph opens app-routing management.
- Navigation → More: routes to · Navigation graph opens settings and logs.
- Connect → Connect VM: observes · Connect screen is driven by ViewModel state.
- Connect VM → Connect State: emits · State object represents connection lifecycle and UI status.
- Connect → Orbot Service: starts/stops · User actions turn into service commands.
- Startup → Orbot Service: launches · Boot and start receivers bring up the backend service.
- Orbot Service → Notifications: publishes status · Service keeps the foreground notification in sync.
- Orbot Service → Tor Config: configures Tor · Service prepares the Tor runtime and resources.
- Orbot Service → VPN: controls · Service delegates VPN setup and teardown.
- VPN → Torified Apps: applies policy · VPN manager uses app torification settings.
- VPN → Tunnel: routes traffic · VPN path hands traffic to the tunnel layer.
- Tunnel → Tor Config: binds to · Tunnel layer depends on Tor-side configuration.
- Connect → Bridges: selects bridges · Connect UI exposes bridge and connection-mode choices.
- Bridges → Bridge Data: loads data · Bridge selection uses bundled bridge and regional data.
- Kindness → Snowflake Proxy: controls · Kindness UI starts and monitors the proxy service.
- Snowflake Proxy → Orbot Service: shares runtime · Snowflake mode runs alongside the app/service ecosystem.
- Onion Services → Client Auth: manages auth · Onion-service hosting is paired with client authorization management.
- Onion Services → Orbot Service: uses backend · Onion-service operations depend on the Tor backend.
- More → Notifications: reads logs/status · More/settings surfaces operational information to the user.
