# sagernet/sing-box-for-android architecture

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

- Interactive diagram: https://gitdiagram.com/sagernet/sing-box-for-android
- Repository: https://github.com/sagernet/sing-box-for-android

## Overview

SFA is an experimental Android client for sing-box. Users import or edit proxy profiles, select a profile, and start the service; the app loads the selected configuration and asks sing-box to start or reload it, using Android VPN support when needed. Separate capabilities include remote control, USB/IP, Taildrop, terminal/SSH, diagnostics, and Xposed-based VPN hiding. Edges are limited to relationships visible in excerpts or the source index; unsampled feature wiring is not inferred.

Main entry points: [`app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt`](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt) (Core service), [`app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt`](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt) (Remote control), [`app/src/main/java/io/nekohasekai/sfa/database/ProfileManager.kt`](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/ProfileManager.kt) (Profile manager), [`app/src/main/java/io/nekohasekai/sfa/database/Settings.kt`](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/Settings.kt) (Settings store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_activity["Main activity<br/>[MainActivity.kt]"]
  node_import["Profile import"]
  node_profileui["Profile editor"]
  node_connections["Connections view"]
  node_tools["Tools screens<br/>[ToolsScreen.kt]"]
end

subgraph group_config["Profiles and settings"]
  node_profiles["Profile manager<br/>[ProfileManager.kt]"]
  node_profiledb[("Profile database<br/>[ProfileDatabase.kt]")]
  node_settings[("Settings store<br/>[Settings.kt]")]
end

subgraph group_runtime["Proxy runtime"]
  node_appinit["Application setup<br/>[Application.kt]"]
  node_boxservice["Core service<br/>[BoxService.kt]"]
  node_vpnservice["VPN service<br/>[VPNService.kt]"]
  node_network["Network monitor"]
  node_command["Command client<br/>[CommandClient.kt]"]
end

subgraph group_features["Integrations and tools"]
  node_remote["Remote control"]
  node_remoteclients["Remote servers"]
  node_taildrop["Taildrop sending"]
  node_taildropservice["Taildrop service"]
  node_usbip["USB/IP manager<br/>[USBIPManager.kt]"]
  node_usbservice["USB/IP service<br/>[USBIPService.kt]"]
  node_terminal["SSH terminal"]
  node_reports["Power reports"]
  node_hook["VPN hide hooks"]
  node_hookerrors[("Hook error store<br/>[HookErrorStore.kt]")]
end

node_user(("Android user"))

node_user -->|"uses"| node_activity
node_import -->|"creates profiles"| node_profiles
node_profiles -->|"queries and updates"| node_profiledb
node_boxservice -->|"loads selected profile"| node_profiles
node_boxservice -->|"reads configuration"| node_settings
node_boxservice -->|"uses VPN mode"| node_vpnservice
node_vpnservice -->|"reads VPN options"| node_settings
node_boxservice -->|"starts monitor"| node_network
node_activity -->|"restores control"| node_remote
node_remote -->|"loads server"| node_remoteclients
node_remote -->|"monitors status"| node_command
node_taildrop -->|"starts service"| node_taildropservice
node_taildrop -->|"sends files"| node_command
node_usbip -->|"starts service"| node_usbservice
node_terminal -->|"uses client"| node_command
node_hook -->|"records errors"| node_hookerrors
node_appinit -->|"initializes settings"| node_settings
node_appinit -->|"configures reports"| node_reports

click node_activity "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/MainActivity.kt"
click node_import "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/configuration/ProfileImportHandler.kt"
click node_profileui "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/profile/EditProfileViewModel.kt"
click node_connections "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/connections/ConnectionsViewModel.kt"
click node_tools "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/ToolsScreen.kt"
click node_appinit "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/Application.kt"
click node_profiles "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/ProfileManager.kt"
click node_profiledb "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/ProfileDatabase.kt"
click node_settings "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/Settings.kt"
click node_boxservice "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt"
click node_vpnservice "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/VPNService.kt"
click node_network "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/DefaultNetworkMonitor.kt"
click node_command "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/utils/CommandClient.kt"
click node_remote "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt"
click node_remoteclients "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/RemoteServerManager.kt"
click node_taildrop "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/TaildropSendManager.kt"
click node_taildropservice "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/TaildropSendService.kt"
click node_usbip "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/usbip/USBIPManager.kt"
click node_usbservice "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/USBIPService.kt"
click node_terminal "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/terminal/TerminalSessionManager.kt"
click node_reports "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/PowerReportManager.kt"
click node_hook "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/xposed/hooks/hidevpn/ConnectivityServiceHookHelper.kt"
click node_hookerrors "https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/xposed/HookErrorStore.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_activity,node_import,node_profileui,node_connections,node_tools,node_user toneBlue
class node_profiles,node_profiledb,node_settings toneAmber
class node_appinit,node_boxservice,node_vpnservice,node_network,node_command toneMint
class node_remote,node_remoteclients,node_taildrop,node_taildropservice,node_usbip,node_usbservice,node_terminal,node_reports,node_hook,node_hookerrors toneRose
```

## Components

### App interface

- [Main activity](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/MainActivity.kt): `app/src/main/java/io/nekohasekai/sfa/compose/MainActivity.kt`
- [Profile import](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/configuration/ProfileImportHandler.kt): `app/src/main/java/io/nekohasekai/sfa/compose/screen/configuration/ProfileImportHandler.kt`
- [Profile editor](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/profile/EditProfileViewModel.kt): `app/src/main/java/io/nekohasekai/sfa/compose/screen/profile/EditProfileViewModel.kt`
- [Connections view](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/connections/ConnectionsViewModel.kt): `app/src/main/java/io/nekohasekai/sfa/compose/screen/connections/ConnectionsViewModel.kt`
- [Tools screens](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/ToolsScreen.kt): `app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/ToolsScreen.kt`

### Profiles and settings

- [Profile manager](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/ProfileManager.kt): `app/src/main/java/io/nekohasekai/sfa/database/ProfileManager.kt`
- [Profile database](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/ProfileDatabase.kt): `app/src/main/java/io/nekohasekai/sfa/database/ProfileDatabase.kt`
- [Settings store](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/Settings.kt): `app/src/main/java/io/nekohasekai/sfa/database/Settings.kt`

### Proxy runtime

- [Application setup](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/Application.kt): `app/src/main/java/io/nekohasekai/sfa/Application.kt`
- [Core service](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt): `app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt`
- [VPN service](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/VPNService.kt): `app/src/main/java/io/nekohasekai/sfa/bg/VPNService.kt`
- [Network monitor](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/DefaultNetworkMonitor.kt): `app/src/main/java/io/nekohasekai/sfa/bg/DefaultNetworkMonitor.kt`
- [Command client](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/utils/CommandClient.kt): `app/src/main/java/io/nekohasekai/sfa/utils/CommandClient.kt`

### Integrations and tools

- [Remote control](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt): `app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt`
- [Remote servers](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/database/RemoteServerManager.kt): `app/src/main/java/io/nekohasekai/sfa/database/RemoteServerManager.kt`
- [Taildrop sending](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/TaildropSendManager.kt): `app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/TaildropSendManager.kt`
- [Taildrop service](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/TaildropSendService.kt): `app/src/main/java/io/nekohasekai/sfa/bg/TaildropSendService.kt`
- [USB/IP manager](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/usbip/USBIPManager.kt): `app/src/main/java/io/nekohasekai/sfa/usbip/USBIPManager.kt`
- [USB/IP service](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/USBIPService.kt): `app/src/main/java/io/nekohasekai/sfa/bg/USBIPService.kt`
- [SSH terminal](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/terminal/TerminalSessionManager.kt): `app/src/main/java/io/nekohasekai/sfa/terminal/TerminalSessionManager.kt`
- [Power reports](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/bg/PowerReportManager.kt): `app/src/main/java/io/nekohasekai/sfa/bg/PowerReportManager.kt`
- [VPN hide hooks](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/xposed/hooks/hidevpn/ConnectivityServiceHookHelper.kt): `app/src/main/java/io/nekohasekai/sfa/xposed/hooks/hidevpn/ConnectivityServiceHookHelper.kt`
- [Hook error store](https://github.com/sagernet/sing-box-for-android/blob/dev/app/src/main/java/io/nekohasekai/sfa/xposed/HookErrorStore.kt): `app/src/main/java/io/nekohasekai/sfa/xposed/HookErrorStore.kt`

### Other components

- **Android user**

## Connections

- Android user → Main activity: uses (evidence: `app/src/main/java/io/nekohasekai/sfa/compose/MainActivity.kt`)
- Profile import → Profile manager: creates profiles (evidence: `app/src/main/java/io/nekohasekai/sfa/compose/screen/configuration/ProfileImportHandler.kt`)
- Profile manager → Profile database: queries and updates (evidence: `app/src/main/java/io/nekohasekai/sfa/database/ProfileManager.kt`)
- Core service → Profile manager: loads selected profile (evidence: `app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt`)
- Core service → Settings store: reads configuration (evidence: `app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt`)
- Core service → VPN service: uses VPN mode (evidence: `app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt`)
- VPN service → Settings store: reads VPN options (evidence: `app/src/main/java/io/nekohasekai/sfa/bg/VPNService.kt`)
- Core service → Network monitor: starts monitor (evidence: `app/src/main/java/io/nekohasekai/sfa/bg/BoxService.kt`)
- Main activity → Remote control: restores control (evidence: `app/src/main/java/io/nekohasekai/sfa/compose/MainActivity.kt`)
- Remote control → Remote servers: loads server (evidence: `app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt`)
- Remote control → Command client: monitors status (evidence: `app/src/main/java/io/nekohasekai/sfa/utils/RemoteControlManager.kt`)
- Taildrop sending → Taildrop service: starts service (evidence: `app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/TaildropSendManager.kt`)
- Taildrop sending → Command client: sends files (evidence: `app/src/main/java/io/nekohasekai/sfa/compose/screen/tools/TaildropSendManager.kt`)
- USB/IP manager → USB/IP service: starts service (evidence: `app/src/main/java/io/nekohasekai/sfa/usbip/USBIPManager.kt`)
- SSH terminal → Command client: uses client (evidence: `app/src/main/java/io/nekohasekai/sfa/terminal/TerminalSessionManager.kt`)
- VPN hide hooks → Hook error store: records errors (evidence: `app/src/main/java/io/nekohasekai/sfa/xposed/hooks/hidevpn/ConnectivityManager+getNetworkCapabilities.kt`)
- Application setup → Settings store: initializes settings (evidence: `app/src/main/java/io/nekohasekai/sfa/Application.kt`)
- Application setup → Power reports: configures reports (evidence: `app/src/main/java/io/nekohasekai/sfa/Application.kt`)