# shadowsocks/shadowsocks-android architecture

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

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

## Overview

Shadowsocks for Android is a proxy client: a user selects a server profile and starts the service, which establishes proxy, transparent-proxy, or VPN routing. The graph includes profile and preference management, ACL routing, subscriptions, plugin support, and boot/direct-boot behavior alongside the main connection workflow. Relationships are limited to the provided excerpts and SOURCE INDEX references; unsampled implementations are represented only where the tree and index support them.

Main entry points: [`core/src/main/java/com/github/shadowsocks/bg/BaseService.kt`](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/BaseService.kt) (Service controller), [`core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt`](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt) (Profile management), [`core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt`](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt) (Service connection), [`mobile/src/main/java/com/github/shadowsocks/MainActivity.kt`](https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/MainActivity.kt) (Main screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client interfaces"]
  node_main_ui["Main screen<br/>[MainActivity.kt]"]
  node_profile_ui["Profile editor"]
  node_tv_ui["TV interface"]
  node_tile["Quick toggle<br/>[TileService.kt]"]
  node_acl_ui["Rule editor"]
  node_subscription_ui["Subscription screen"]
end

subgraph group_connection["Connection runtime"]
  node_connection_api["Service connection"]
  node_service_base["Service controller<br/>[BaseService.kt]"]
  node_vpn_runtime["VPN routing<br/>[VpnService.kt]"]
  node_proxy_runtime["Proxy mode<br/>[ProxyService.kt]"]
  node_transproxy_runtime["Transparent proxy"]
  node_processes["Proxy processes<br/>[Executable.kt]"]
end

subgraph group_configuration["Profiles and settings"]
  node_acl["Access rules<br/>[Acl.kt]"]
  node_profiles["Profile management<br/>[ProfileManager.kt]"]
  node_profile_model["Profile model<br/>[Profile.kt]"]
  node_database[("Profile database<br/>[PrivateDatabase.kt]")]
  node_settings[("Settings store<br/>[DataStore.kt]")]
  node_direct_boot["Direct boot state<br/>[DirectBoot.kt]"]
  node_boot["Boot receiver<br/>[BootReceiver.kt]"]
end

subgraph group_extensions["Supporting capabilities"]
  node_subscriptions["Subscription service"]
  node_subscription_model["Subscription data<br/>[Subscription.kt]"]
  node_plugins["Plugin manager<br/>[PluginManager.kt]"]
  node_plugin_options["Plugin options<br/>[PluginOptions.kt]"]
end

node_user(("User"))
node_network["Android network"]

node_user -->|"configures and starts"| node_main_ui
node_main_ui -->|"connects to"| node_connection_api
node_tv_ui -->|"connects to"| node_connection_api
node_tile -->|"toggles service"| node_connection_api
node_connection_api -->|"binds service"| node_service_base
node_service_base -->|"dispatches mode"| node_vpn_runtime
node_service_base -->|"dispatches mode"| node_proxy_runtime
node_service_base -->|"dispatches mode"| node_transproxy_runtime
node_service_base -->|"starts processes"| node_processes
node_vpn_runtime -->|"routes VPN traffic"| node_network
node_service_base -->|"loads rules"| node_acl
node_acl_ui -->|"edits rules"| node_acl
node_main_ui -.->|"selects profile"| node_profiles
node_profile_ui -.->|"edits profile"| node_profiles
node_profiles -->|"manages profiles"| node_profile_model
node_profiles -->|"reads and writes"| node_database
node_profiles -->|"updates boot profile"| node_direct_boot
node_service_base -->|"reads configuration"| node_settings
node_boot -.->|"starts on boot"| node_service_base
node_subscriptions -->|"creates profiles"| node_profiles
node_subscriptions -->|"processes subscription"| node_subscription_model
node_subscription_ui -->|"manages subscriptions"| node_subscriptions
node_service_base -.->|"resolves plugins"| node_plugins
node_plugins -->|"handles options"| node_plugin_options

click node_main_ui "https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/MainActivity.kt"
click node_profile_ui "https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/ProfileConfigActivity.kt"
click node_tv_ui "https://github.com/shadowsocks/shadowsocks-android/blob/master/tv/src/main/java/com/github/shadowsocks/tv/MainPreferenceFragment.kt"
click node_tile "https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/bg/TileService.kt"
click node_connection_api "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt"
click node_service_base "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/BaseService.kt"
click node_vpn_runtime "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/VpnService.kt"
click node_proxy_runtime "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/ProxyService.kt"
click node_transproxy_runtime "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/TransproxyService.kt"
click node_processes "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/Executable.kt"
click node_acl "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/acl/Acl.kt"
click node_acl_ui "https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/acl/CustomRulesFragment.kt"
click node_profiles "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt"
click node_profile_model "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/Profile.kt"
click node_database "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/PrivateDatabase.kt"
click node_settings "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/preference/DataStore.kt"
click node_direct_boot "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/utils/DirectBoot.kt"
click node_boot "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/BootReceiver.kt"
click node_subscriptions "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/subscription/SubscriptionService.kt"
click node_subscription_model "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/subscription/Subscription.kt"
click node_subscription_ui "https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/subscription/SubscriptionFragment.kt"
click node_plugins "https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/plugin/PluginManager.kt"
click node_plugin_options "https://github.com/shadowsocks/shadowsocks-android/blob/master/plugin/src/main/java/com/github/shadowsocks/plugin/PluginOptions.kt"

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_main_ui,node_profile_ui,node_tv_ui,node_tile,node_acl_ui,node_subscription_ui,node_user toneBlue
class node_connection_api,node_service_base,node_vpn_runtime,node_proxy_runtime,node_transproxy_runtime,node_processes toneAmber
class node_acl,node_profiles,node_profile_model,node_database,node_settings,node_direct_boot,node_boot toneMint
class node_subscriptions,node_subscription_model,node_plugins,node_plugin_options toneRose
class node_network toneIndigo
```

## Components

### Client interfaces

- [Main screen](https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/MainActivity.kt): `mobile/src/main/java/com/github/shadowsocks/MainActivity.kt`
- [Profile editor](https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/ProfileConfigActivity.kt): `mobile/src/main/java/com/github/shadowsocks/ProfileConfigActivity.kt`
- [TV interface](https://github.com/shadowsocks/shadowsocks-android/blob/master/tv/src/main/java/com/github/shadowsocks/tv/MainPreferenceFragment.kt): `tv/src/main/java/com/github/shadowsocks/tv/MainPreferenceFragment.kt`
- [Quick toggle](https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/bg/TileService.kt): `mobile/src/main/java/com/github/shadowsocks/bg/TileService.kt`
- [Rule editor](https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/acl/CustomRulesFragment.kt): `mobile/src/main/java/com/github/shadowsocks/acl/CustomRulesFragment.kt`
- [Subscription screen](https://github.com/shadowsocks/shadowsocks-android/blob/master/mobile/src/main/java/com/github/shadowsocks/subscription/SubscriptionFragment.kt): `mobile/src/main/java/com/github/shadowsocks/subscription/SubscriptionFragment.kt`

### Connection runtime

- [Service connection](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt): `core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt`
- [Service controller](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/BaseService.kt): `core/src/main/java/com/github/shadowsocks/bg/BaseService.kt`
- [VPN routing](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/VpnService.kt): `core/src/main/java/com/github/shadowsocks/bg/VpnService.kt`
- [Proxy mode](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/ProxyService.kt): `core/src/main/java/com/github/shadowsocks/bg/ProxyService.kt`
- [Transparent proxy](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/TransproxyService.kt): `core/src/main/java/com/github/shadowsocks/bg/TransproxyService.kt`
- [Proxy processes](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/bg/Executable.kt): `core/src/main/java/com/github/shadowsocks/bg/Executable.kt`

### Profiles and settings

- [Access rules](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/acl/Acl.kt): `core/src/main/java/com/github/shadowsocks/acl/Acl.kt`
- [Profile management](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt): `core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt`
- [Profile model](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/Profile.kt): `core/src/main/java/com/github/shadowsocks/database/Profile.kt`
- [Profile database](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/database/PrivateDatabase.kt): `core/src/main/java/com/github/shadowsocks/database/PrivateDatabase.kt`
- [Settings store](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/preference/DataStore.kt): `core/src/main/java/com/github/shadowsocks/preference/DataStore.kt`
- [Direct boot state](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/utils/DirectBoot.kt): `core/src/main/java/com/github/shadowsocks/utils/DirectBoot.kt`
- [Boot receiver](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/BootReceiver.kt): `core/src/main/java/com/github/shadowsocks/BootReceiver.kt`

### Supporting capabilities

- [Subscription service](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/subscription/SubscriptionService.kt): `core/src/main/java/com/github/shadowsocks/subscription/SubscriptionService.kt`
- [Subscription data](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/subscription/Subscription.kt): `core/src/main/java/com/github/shadowsocks/subscription/Subscription.kt`
- [Plugin manager](https://github.com/shadowsocks/shadowsocks-android/blob/master/core/src/main/java/com/github/shadowsocks/plugin/PluginManager.kt): `core/src/main/java/com/github/shadowsocks/plugin/PluginManager.kt`
- [Plugin options](https://github.com/shadowsocks/shadowsocks-android/blob/master/plugin/src/main/java/com/github/shadowsocks/plugin/PluginOptions.kt): `plugin/src/main/java/com/github/shadowsocks/plugin/PluginOptions.kt`

### Other components

- **User**
- **Android network**

## Connections

- User → Main screen: configures and starts
- Main screen → Service connection: connects to (evidence: `mobile/src/main/java/com/github/shadowsocks/MainActivity.kt`)
- TV interface → Service connection: connects to (evidence: `tv/src/main/java/com/github/shadowsocks/tv/MainPreferenceFragment.kt`)
- Quick toggle → Service connection: toggles service (evidence: `mobile/src/main/java/com/github/shadowsocks/bg/TileService.kt`)
- Service connection → Service controller: binds service (evidence: `core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt`)
- Service controller → VPN routing: dispatches mode (evidence: `core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt`)
- Service controller → Proxy mode: dispatches mode (evidence: `core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt`)
- Service controller → Transparent proxy: dispatches mode (evidence: `core/src/main/java/com/github/shadowsocks/aidl/ShadowsocksConnection.kt`)
- Service controller → Proxy processes: starts processes (evidence: `core/src/main/java/com/github/shadowsocks/bg/BaseService.kt`)
- VPN routing → Android network: routes VPN traffic (evidence: `core/src/main/java/com/github/shadowsocks/bg/VpnService.kt`)
- Service controller → Access rules: loads rules (evidence: `core/src/main/java/com/github/shadowsocks/bg/BaseService.kt`)
- Rule editor → Access rules: edits rules (evidence: `mobile/src/main/java/com/github/shadowsocks/acl/CustomRulesFragment.kt`)
- Main screen → Profile management: selects profile
- Profile editor → Profile management: edits profile
- Profile management → Profile model: manages profiles (evidence: `core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt`)
- Profile management → Profile database: reads and writes (evidence: `core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt`)
- Profile management → Direct boot state: updates boot profile (evidence: `core/src/main/java/com/github/shadowsocks/database/ProfileManager.kt`)
- Service controller → Settings store: reads configuration (evidence: `core/src/main/java/com/github/shadowsocks/bg/BaseService.kt`)
- Boot receiver → Service controller: starts on boot (evidence: `core/src/main/java/com/github/shadowsocks/bg/BaseService.kt`)
- Subscription service → Profile management: creates profiles (evidence: `core/src/main/java/com/github/shadowsocks/subscription/SubscriptionService.kt`)
- Subscription service → Subscription data: processes subscription (evidence: `core/src/main/java/com/github/shadowsocks/subscription/SubscriptionService.kt`)
- Subscription screen → Subscription service: manages subscriptions (evidence: `mobile/src/main/java/com/github/shadowsocks/subscription/SubscriptionFragment.kt`)
- Service controller → Plugin manager: resolves plugins (evidence: `core/src/main/java/com/github/shadowsocks/plugin/PluginManager.kt`)
- Plugin manager → Plugin options: handles options (evidence: `core/src/main/java/com/github/shadowsocks/plugin/PluginManager.kt`)
