# shadowsocks/shadowsocksx-ng architecture

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

## Overview

ShadowsocksX-NG2 is a native macOS Shadowsocks client. Users manage server configurations and subscriptions, choose routing rules and proxy mode, activate a target, then the app derives a runtime configuration and supervises local SOCKS5/HTTP listeners; system proxy control is a separate effect. The graph also retains documented rule editing, connectivity checks, plugins, and diagnostic reporting. Several capabilities are represented at their exact enclosing directories because their implementations were not sampled; their links are documented in the README rather than inferred from module names.

Main entry points: [`ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift`](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift) (Runtime controller), [`ShadowsocksX-NG2/App/Application/CatalogWorkflow`](https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/App/Application/CatalogWorkflow) (Catalog workflow), [`ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift`](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift) (Target activation), [`ShadowsocksX-NG2/Agent/main.swift`](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Agent/main.swift) (Launch agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Server catalog"]
  node_catalog_workflow["Catalog workflow"]
  node_catalog_domain["Configuration catalog"]
  node_catalog_store[("Encrypted library")]
  node_subscriptions["Subscriptions"]
end

subgraph group_routing["Routing and plugins"]
  node_activation["Target activation"]
  node_rules["Routing rules"]
  node_plugins["Plugin catalog"]
end

subgraph group_runtime["Proxy runtime"]
  node_runtime_controller["Runtime controller"]
  node_runtime_document["Runtime document"]
  node_runtime_files[("Runtime files")]
  node_agent["Launch agent<br/>[main.swift]"]
  node_sslocal["Upstream sslocal"]
  node_settings["Listener settings"]
end

subgraph group_system["System integration"]
  node_app["Menu bar app<br/>[MainApp.swift]"]
  node_system_proxy["System proxy helper<br/>[main.swift]"]
  node_proxy_service["Helper service client"]
end

subgraph group_support["Connectivity and diagnostics"]
  node_connectivity["Connectivity tests"]
  node_diagnostics["Diagnostic reports"]
end

node_user(("Mac user"))

node_user -->|"uses"| node_app
node_app -.->|"manages"| node_catalog_workflow
node_catalog_workflow -.->|"edits"| node_catalog_domain
node_catalog_domain -->|"persists"| node_catalog_store
node_catalog_workflow -.->|"refreshes"| node_subscriptions
node_catalog_workflow -.->|"activates"| node_activation
node_activation -->|"expands target"| node_catalog_domain
node_activation -.->|"resolves plugins"| node_plugins
node_app -.->|"controls proxy"| node_runtime_controller
node_runtime_controller -->|"deploys document"| node_runtime_document
node_runtime_controller -->|"reads listener settings"| node_settings
node_runtime_controller -.->|"applies saved rules"| node_rules
node_runtime_controller -->|"writes runtime files"| node_runtime_files
node_runtime_controller -->|"registers and signals"| node_agent
node_agent -->|"reads contract"| node_runtime_files
node_agent -->|"supervises"| node_sslocal
node_runtime_document -->|"configures listeners"| node_sslocal
node_settings -->|"defines listeners"| node_runtime_document
node_runtime_controller -->|"requests system proxy"| node_proxy_service
node_proxy_service -->|"sends helper requests"| node_system_proxy
node_system_proxy -.->|"changes macOS proxy"| node_user
node_user -->|"chooses routing mode"| node_rules
node_user -->|"tests latency"| node_connectivity
node_user -->|"requests report"| node_diagnostics

click node_app "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Composition/MainApp.swift"
click node_catalog_workflow "https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/App/Application/CatalogWorkflow"
click node_catalog_domain "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Catalog/ConfigurationCatalog.swift"
click node_catalog_store "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Catalog/ServerLibraryStorage.swift"
click node_subscriptions "https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/Domain/Subscription"
click node_activation "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift"
click node_rules "https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/Domain/Rules"
click node_plugins "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Plugin/PluginCatalog.swift"
click node_runtime_controller "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift"
click node_runtime_document "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Runtime/SslocalRuntimeDocument.swift"
click node_runtime_files "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Runtime/RuntimeFileStore.swift"
click node_agent "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Agent/main.swift"
click node_settings "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Runtime/ProxyListeningConfiguration.swift"
click node_system_proxy "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/SystemProxyHelper/main.swift"
click node_proxy_service "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Application/Services/SystemProxyHelperService.swift"
click node_connectivity "https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/App/Application/Connectivity"
click node_diagnostics "https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Diagnostics/DiagnosticReport.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_catalog_workflow,node_catalog_domain,node_catalog_store,node_subscriptions,node_user toneBlue
class node_activation,node_rules,node_plugins toneAmber
class node_runtime_controller,node_runtime_document,node_runtime_files,node_agent,node_sslocal,node_settings toneMint
class node_app,node_system_proxy,node_proxy_service toneRose
class node_connectivity,node_diagnostics toneIndigo
```

## Components

### Server catalog

- [Catalog workflow](https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/App/Application/CatalogWorkflow): `ShadowsocksX-NG2/App/Application/CatalogWorkflow`
- [Configuration catalog](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Catalog/ConfigurationCatalog.swift): `ShadowsocksX-NG2/Domain/Catalog/ConfigurationCatalog.swift`
- [Encrypted library](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Catalog/ServerLibraryStorage.swift): `ShadowsocksX-NG2/Domain/Catalog/ServerLibraryStorage.swift`
- [Subscriptions](https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/Domain/Subscription): `ShadowsocksX-NG2/Domain/Subscription`

### Routing and plugins

- [Target activation](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift): `ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift`
- [Routing rules](https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/Domain/Rules): `ShadowsocksX-NG2/Domain/Rules`
- [Plugin catalog](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Plugin/PluginCatalog.swift): `ShadowsocksX-NG2/Domain/Plugin/PluginCatalog.swift`

### Proxy runtime

- [Runtime controller](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift): `ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift`
- [Runtime document](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Runtime/SslocalRuntimeDocument.swift): `ShadowsocksX-NG2/Domain/Runtime/SslocalRuntimeDocument.swift`
- [Runtime files](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Runtime/RuntimeFileStore.swift): `ShadowsocksX-NG2/Domain/Runtime/RuntimeFileStore.swift`
- [Launch agent](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Agent/main.swift): `ShadowsocksX-NG2/Agent/main.swift`
- **Upstream sslocal**
- [Listener settings](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Runtime/ProxyListeningConfiguration.swift): `ShadowsocksX-NG2/Domain/Runtime/ProxyListeningConfiguration.swift`

### System integration

- [Menu bar app](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Composition/MainApp.swift): `ShadowsocksX-NG2/App/Composition/MainApp.swift`
- [System proxy helper](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/SystemProxyHelper/main.swift): `ShadowsocksX-NG2/SystemProxyHelper/main.swift`
- [Helper service client](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/App/Application/Services/SystemProxyHelperService.swift): `ShadowsocksX-NG2/App/Application/Services/SystemProxyHelperService.swift`

### Connectivity and diagnostics

- [Connectivity tests](https://github.com/shadowsocks/shadowsocksx-ng/tree/develop/ShadowsocksX-NG2/App/Application/Connectivity): `ShadowsocksX-NG2/App/Application/Connectivity`
- [Diagnostic reports](https://github.com/shadowsocks/shadowsocksx-ng/blob/develop/ShadowsocksX-NG2/Domain/Diagnostics/DiagnosticReport.swift): `ShadowsocksX-NG2/Domain/Diagnostics/DiagnosticReport.swift`

### Other components

- **Mac user**

## Connections

- Mac user → Menu bar app: uses (evidence: `README.md`)
- Menu bar app → Catalog workflow: manages
- Catalog workflow → Configuration catalog: edits
- Configuration catalog → Encrypted library: persists (evidence: `ShadowsocksX-NG2/Domain/Catalog/ServerLibraryStorage.swift`)
- Catalog workflow → Subscriptions: refreshes (evidence: `README.md`)
- Catalog workflow → Target activation: activates
- Target activation → Configuration catalog: expands target (evidence: `ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift`)
- Target activation → Plugin catalog: resolves plugins (evidence: `ShadowsocksX-NG2/Domain/Activation/ActivationStateMachine.swift`)
- Menu bar app → Runtime controller: controls proxy
- Runtime controller → Runtime document: deploys document (evidence: `ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController+Commands.swift`)
- Runtime controller → Listener settings: reads listener settings (evidence: `ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController+SettingsSync.swift`)
- Runtime controller → Routing rules: applies saved rules (evidence: `ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift`)
- Runtime controller → Runtime files: writes runtime files (evidence: `ShadowsocksX-NG2/App/Application/ProxyRuntime/ProxyRuntimeController.swift`)
- Runtime controller → Launch agent: registers and signals
- Launch agent → Runtime files: reads contract (evidence: `ShadowsocksX-NG2/Agent/main.swift`)
- Launch agent → Upstream sslocal: supervises (evidence: `ShadowsocksX-NG2/Agent/main.swift`)
- Runtime document → Upstream sslocal: configures listeners (evidence: `README.md`)
- Listener settings → Runtime document: defines listeners (evidence: `ShadowsocksX-NG2/Domain/Runtime/SslocalRuntimeDocument.swift`)
- Runtime controller → Helper service client: requests system proxy (evidence: `ShadowsocksX-NG2/App/Application/Services/SystemProxyHelperService.swift`)
- Helper service client → System proxy helper: sends helper requests (evidence: `ShadowsocksX-NG2/App/Application/Services/SystemProxyHelperService.swift`)
- System proxy helper → Mac user: changes macOS proxy (evidence: `README.md`)
- Mac user → Routing rules: chooses routing mode (evidence: `README.md`)
- Mac user → Connectivity tests: tests latency (evidence: `README.md`)
- Mac user → Diagnostic reports: requests report (evidence: `README.md`)