# matsuridayo/nekoboxforandroid architecture

> Architecture diagram of the GitHub repository matsuridayo/nekoboxforandroid, 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/matsuridayo/nekoboxforandroid
- Repository: https://github.com/matsuridayo/nekoboxforandroid

## Overview

NekoBox for Android is a sing-box-based universal proxy client. The main workflow is configuring proxy profiles and routing preferences, selecting a profile, then starting a background proxy service (including Android VPN mode) to handle traffic; subscription updates, plugins, protocol formats, and connection testing are additional capabilities. The graph combines README claims with the supplied source excerpts and SOURCE INDEX references; several implementation details are unsampled, so uncertain links are omitted or marked dashed.

Main entry points: [`app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt`](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt) (Service lifecycle), [`app/src/main/java/io/nekohasekai/sagernet/bg/proto/ProxyInstance.kt`](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/proto/ProxyInstance.kt) (Proxy instance), [`app/src/main/java/io/nekohasekai/sagernet/ui/MainActivity.kt`](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/MainActivity.kt) (Main interface), [`app/src/main/java/io/nekohasekai/sagernet/database/DataStore.kt`](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/DataStore.kt) (Runtime preferences)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Profiles and routing"]
  node_profile_ui["Profile editor"]
  node_route_ui["Route editor"]
  node_profile_manager["Profile manager<br/>[ProfileManager.kt]"]
  node_group_manager["Group manager<br/>[GroupManager.kt]"]
  node_profile_store[("Profiles and rules<br/>[SagerDatabase.kt]")]
  node_settings[("Runtime preferences<br/>[DataStore.kt]")]
  node_subscription["Subscription updates"]
  node_app_selection["Per-app routing"]
end

subgraph group_runtime["Proxy runtime"]
  node_service["Service lifecycle<br/>[BaseService.kt]"]
  node_proxy_instance["Proxy instance<br/>[ProxyInstance.kt]"]
  node_vpn["VPN tunnel<br/>[VpnService.kt]"]
  node_notification["Service controls"]
  node_traffic["Traffic monitoring<br/>[TrafficUpdater.kt]"]
end

subgraph group_integration["Protocols and integrations"]
  node_formats["Proxy formats"]
  node_plugins["Plugin manager<br/>[PluginManager.kt]"]
  node_native_core["Native core<br/>[box.go]"]
end

subgraph group_android["Android app shell"]
  node_main_ui["Main interface<br/>[MainActivity.kt]"]
  node_app_init["Application setup<br/>[SagerNet.kt]"]
  node_network["Network monitor"]
end

node_user(("User"))

node_user -.->|"configures"| node_main_ui
node_main_ui -.->|"edits profiles"| node_profile_ui
node_main_ui -.->|"edits routing"| node_route_ui
node_route_ui -->|"saves preferences"| node_settings
node_route_ui -->|"creates rules"| node_profile_manager
node_profile_manager -->|"reads and writes"| node_profile_store
node_group_manager -->|"reads and writes"| node_profile_store
node_group_manager -->|"reconfigures"| node_subscription
node_profile_manager -->|"persists profiles"| node_profile_store
node_app_init -->|"initializes with"| node_settings
node_app_init -->|"starts monitor"| node_network
node_app_init -->|"references"| node_main_ui
node_service -->|"launches"| node_proxy_instance
node_service -->|"manages"| node_notification
node_vpn -->|"extends"| node_service
node_service -->|"reads settings"| node_settings
node_proxy_instance -.->|"loads plugins"| node_plugins
node_proxy_instance -.->|"uses protocol configs"| node_formats
node_proxy_instance -.->|"starts core"| node_native_core
node_service -.->|"updates traffic"| node_traffic
node_app_selection -->|"stores app selection"| node_settings

click node_main_ui "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/MainActivity.kt"
click node_profile_ui "https://github.com/matsuridayo/nekoboxforandroid/tree/main/app/src/main/java/io/nekohasekai/sagernet/ui/profile"
click node_route_ui "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/RouteSettingsActivity.kt"
click node_profile_manager "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/ProfileManager.kt"
click node_group_manager "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/GroupManager.kt"
click node_profile_store "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/SagerDatabase.kt"
click node_settings "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/DataStore.kt"
click node_subscription "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/SubscriptionUpdater.kt"
click node_service "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt"
click node_proxy_instance "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/proto/ProxyInstance.kt"
click node_vpn "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/VpnService.kt"
click node_notification "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/ServiceNotification.kt"
click node_traffic "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/proto/TrafficUpdater.kt"
click node_formats "https://github.com/matsuridayo/nekoboxforandroid/tree/main/app/src/main/java/io/nekohasekai/sagernet/fmt"
click node_plugins "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/plugin/PluginManager.kt"
click node_native_core "https://github.com/matsuridayo/nekoboxforandroid/blob/main/libcore/box.go"
click node_app_init "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/SagerNet.kt"
click node_network "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/utils/DefaultNetworkListener.kt"
click node_app_selection "https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/AppManagerActivity.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_profile_ui,node_route_ui,node_profile_manager,node_group_manager,node_profile_store,node_settings,node_subscription,node_app_selection,node_user toneBlue
class node_service,node_proxy_instance,node_vpn,node_notification,node_traffic toneAmber
class node_formats,node_plugins,node_native_core toneMint
class node_main_ui,node_app_init,node_network toneRose
```

## Components

### Profiles and routing

- [Profile editor](https://github.com/matsuridayo/nekoboxforandroid/tree/main/app/src/main/java/io/nekohasekai/sagernet/ui/profile): `app/src/main/java/io/nekohasekai/sagernet/ui/profile`
- [Route editor](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/RouteSettingsActivity.kt): `app/src/main/java/io/nekohasekai/sagernet/ui/RouteSettingsActivity.kt`
- [Profile manager](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/ProfileManager.kt): `app/src/main/java/io/nekohasekai/sagernet/database/ProfileManager.kt`
- [Group manager](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/GroupManager.kt): `app/src/main/java/io/nekohasekai/sagernet/database/GroupManager.kt`
- [Profiles and rules](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/SagerDatabase.kt): `app/src/main/java/io/nekohasekai/sagernet/database/SagerDatabase.kt`
- [Runtime preferences](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/database/DataStore.kt): `app/src/main/java/io/nekohasekai/sagernet/database/DataStore.kt`
- [Subscription updates](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/SubscriptionUpdater.kt): `app/src/main/java/io/nekohasekai/sagernet/bg/SubscriptionUpdater.kt`
- [Per-app routing](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/AppManagerActivity.kt): `app/src/main/java/io/nekohasekai/sagernet/ui/AppManagerActivity.kt`

### Proxy runtime

- [Service lifecycle](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt): `app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt`
- [Proxy instance](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/proto/ProxyInstance.kt): `app/src/main/java/io/nekohasekai/sagernet/bg/proto/ProxyInstance.kt`
- [VPN tunnel](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/VpnService.kt): `app/src/main/java/io/nekohasekai/sagernet/bg/VpnService.kt`
- [Service controls](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/ServiceNotification.kt): `app/src/main/java/io/nekohasekai/sagernet/bg/ServiceNotification.kt`
- [Traffic monitoring](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/bg/proto/TrafficUpdater.kt): `app/src/main/java/io/nekohasekai/sagernet/bg/proto/TrafficUpdater.kt`

### Protocols and integrations

- [Proxy formats](https://github.com/matsuridayo/nekoboxforandroid/tree/main/app/src/main/java/io/nekohasekai/sagernet/fmt): `app/src/main/java/io/nekohasekai/sagernet/fmt`
- [Plugin manager](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/plugin/PluginManager.kt): `app/src/main/java/io/nekohasekai/sagernet/plugin/PluginManager.kt`
- [Native core](https://github.com/matsuridayo/nekoboxforandroid/blob/main/libcore/box.go): `libcore/box.go`

### Android app shell

- [Main interface](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/ui/MainActivity.kt): `app/src/main/java/io/nekohasekai/sagernet/ui/MainActivity.kt`
- [Application setup](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/SagerNet.kt): `app/src/main/java/io/nekohasekai/sagernet/SagerNet.kt`
- [Network monitor](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/src/main/java/io/nekohasekai/sagernet/utils/DefaultNetworkListener.kt): `app/src/main/java/io/nekohasekai/sagernet/utils/DefaultNetworkListener.kt`

### Other components

- **User**

## Connections

- User → Main interface: configures (evidence: `README.md`)
- Main interface → Profile editor: edits profiles
- Main interface → Route editor: edits routing
- Route editor → Runtime preferences: saves preferences (evidence: `app/src/main/java/io/nekohasekai/sagernet/ui/RouteSettingsActivity.kt`)
- Route editor → Profile manager: creates rules (evidence: `app/src/main/java/io/nekohasekai/sagernet/ui/RouteSettingsActivity.kt`)
- Profile manager → Profiles and rules: reads and writes (evidence: `app/src/main/java/io/nekohasekai/sagernet/database/ProfileManager.kt`)
- Group manager → Profiles and rules: reads and writes (evidence: `app/src/main/java/io/nekohasekai/sagernet/database/GroupManager.kt`)
- Group manager → Subscription updates: reconfigures (evidence: `app/src/main/java/io/nekohasekai/sagernet/database/GroupManager.kt`)
- Profile manager → Profiles and rules: persists profiles (evidence: `app/src/main/java/io/nekohasekai/sagernet/database/ProfileManager.kt`)
- Application setup → Runtime preferences: initializes with (evidence: `app/src/main/java/io/nekohasekai/sagernet/SagerNet.kt`)
- Application setup → Network monitor: starts monitor (evidence: `app/src/main/java/io/nekohasekai/sagernet/SagerNet.kt`)
- Application setup → Main interface: references (evidence: `app/src/main/java/io/nekohasekai/sagernet/SagerNet.kt`)
- Service lifecycle → Proxy instance: launches (evidence: `app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt`)
- Service lifecycle → Service controls: manages (evidence: `app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt`)
- VPN tunnel → Service lifecycle: extends (evidence: `app/src/main/java/io/nekohasekai/sagernet/bg/VpnService.kt`)
- Service lifecycle → Runtime preferences: reads settings (evidence: `app/src/main/java/io/nekohasekai/sagernet/bg/BaseService.kt`)
- Proxy instance → Plugin manager: loads plugins
- Proxy instance → Proxy formats: uses protocol configs
- Proxy instance → Native core: starts core
- Service lifecycle → Traffic monitoring: updates traffic
- Per-app routing → Runtime preferences: stores app selection (evidence: `app/src/main/java/io/nekohasekai/sagernet/ui/AppManagerActivity.kt`)
