# ladybug-w/clashx architecture

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

- Interactive diagram: https://gitdiagram.com/ladybug-w/clashx
- Repository: https://github.com/ladybug-w/clashx

## Overview

ClashX is a macOS menu-bar client for the Clash rule-based proxy. Users configure or import a YAML profile, start the Clash core, choose proxy groups and modes from the status menu, and optionally route macOS system traffic through the proxy. The app also exposes dashboard/API controls, remote-control profiles, and privileged proxy-setting operations. The README documents HTTP(S)/SOCKS, GeoIP, VMess/Shadowsocks/SOCKS5, and TCP redirect capabilities, but the sampled files do not show their engine internals. Edges reflect shown calls or indexed references; unverified core wiring is dashed.

Main entry points: [`ClashX/AppDelegate.swift`](https://github.com/ladybug-w/clashx/blob/master/ClashX/AppDelegate.swift) (App coordinator), [`ClashX/General/Managers/ConfigManager.swift`](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConfigManager.swift) (Config state), [`ClashX/General/ApiRequest.swift`](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/ApiRequest.swift) (Core API client), [`ClashX/General/Managers/MenuItemFactory.swift`](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/MenuItemFactory.swift) (Proxy menu factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App lifecycle"]
  node_delegate["App coordinator<br/>[AppDelegate.swift]"]
  node_status["Status menu"]
  node_dashboard["Dashboard web view"]
  node_externalui["External control UI"]
end

subgraph group_config["Configuration"]
  node_configmanager["Config state"]
  node_configfiles["Config files"]
  node_configmodel["Config model<br/>[ClashConfig.swift]"]
  node_remoteconfig["Remote profiles"]
  node_remotemodel["Remote profile model"]
  node_savedproxy[("Saved selections")]
end

subgraph group_proxy["Proxy control"]
  node_proxydata["Proxy models<br/>[ClashProxy.swift]"]
  node_menuitems["Proxy menu factory"]
  node_proxyview["Proxy menu items"]
  node_remotecontrol["Remote control"]
  node_sysproxy["System proxy manager"]
  node_helper["Privileged helper client"]
  node_helperprotocol["Proxy helper protocol"]
end

subgraph group_runtime["Runtime services"]
  node_engine["Clash core<br/>[main.go]"]
  node_api["Core API client<br/>[ApiRequest.swift]"]
  node_connection["Connection status"]
  node_log["Logging<br/>[Logger.swift]"]
end

node_user(("Mac user"))

node_user -.->|"launches"| node_delegate
node_delegate -->|"creates"| node_status
node_delegate -->|"copies sample"| node_configfiles
node_delegate -.->|"starts proxy"| node_configmanager
node_delegate -->|"coordinates"| node_remoteconfig
node_delegate -->|"configures menu"| node_sysproxy
node_delegate -->|"adds menu option"| node_connection
node_configmanager -->|"watches files"| node_configfiles
node_configmanager -.->|"holds current"| node_configmodel
node_configmanager -->|"persists selections"| node_savedproxy
node_remoteconfig -->|"uses model"| node_remotemodel
node_remoteconfig -->|"updates state"| node_configmanager
node_externalui -->|"controls"| node_remotecontrol
node_remotecontrol -->|"sets API override"| node_configmanager
node_remotecontrol -->|"recreates menus"| node_menuitems
node_menuitems -->|"requests proxy data"| node_api
node_menuitems -->|"builds menus from"| node_proxydata
node_menuitems -->|"creates items"| node_proxyview
node_proxyview -->|"displays"| node_proxydata
node_connection -->|"requests status"| node_api
node_api -->|"decodes config"| node_configmodel
node_dashboard -.->|"uses API"| node_api
node_delegate -.->|"starts core"| node_engine
node_api -.->|"calls core API"| node_engine
node_sysproxy -->|"reads ports"| node_configmanager
node_sysproxy -->|"requests proxy changes"| node_helper
node_helper -.->|"uses protocol"| node_helperprotocol
node_helper -->|"logs operations"| node_log

click node_delegate "https://github.com/ladybug-w/clashx/blob/master/ClashX/AppDelegate.swift"
click node_status "https://github.com/ladybug-w/clashx/blob/master/ClashX/Views/StatusItemView.swift"
click node_dashboard "https://github.com/ladybug-w/clashx/blob/master/ClashX/ViewControllers/ClashWebViewContoller.swift"
click node_externalui "https://github.com/ladybug-w/clashx/blob/master/ClashX/ViewControllers/ExternalControlViewController.swift"
click node_configmanager "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConfigManager.swift"
click node_configfiles "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConfigFileManager.swift"
click node_configmodel "https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/ClashConfig.swift"
click node_remoteconfig "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/RemoteConfigManager.swift"
click node_remotemodel "https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/RemoteConfigModel.swift"
click node_savedproxy "https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/SavedProxyModel.swift"
click node_engine "https://github.com/ladybug-w/clashx/blob/master/ClashX/goClash/main.go"
click node_api "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/ApiRequest.swift"
click node_connection "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConnectionManager.swift"
click node_proxydata "https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/ClashProxy.swift"
click node_menuitems "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/MenuItemFactory.swift"
click node_proxyview "https://github.com/ladybug-w/clashx/blob/master/ClashX/Views/ProxyMenuItem.swift"
click node_remotecontrol "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/RemoteControlManager.swift"
click node_sysproxy "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/SystemProxyManager.swift"
click node_helper "https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/PrivilegedHelperManager.swift"
click node_helperprotocol "https://github.com/ladybug-w/clashx/blob/master/ProxyConfigHelper/ProxyConfigRemoteProcessProtocol.h"
click node_log "https://github.com/ladybug-w/clashx/blob/master/ClashX/Basic/Logger.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_delegate,node_status,node_dashboard,node_externalui,node_user toneBlue
class node_configmanager,node_configfiles,node_configmodel,node_remoteconfig,node_remotemodel,node_savedproxy toneAmber
class node_proxydata,node_menuitems,node_proxyview,node_remotecontrol,node_sysproxy,node_helper,node_helperprotocol toneMint
class node_engine,node_api,node_connection,node_log toneRose
```

## Components

### App lifecycle

- [App coordinator](https://github.com/ladybug-w/clashx/blob/master/ClashX/AppDelegate.swift): `ClashX/AppDelegate.swift`
- [Status menu](https://github.com/ladybug-w/clashx/blob/master/ClashX/Views/StatusItemView.swift): `ClashX/Views/StatusItemView.swift`
- [Dashboard web view](https://github.com/ladybug-w/clashx/blob/master/ClashX/ViewControllers/ClashWebViewContoller.swift): `ClashX/ViewControllers/ClashWebViewContoller.swift`
- [External control UI](https://github.com/ladybug-w/clashx/blob/master/ClashX/ViewControllers/ExternalControlViewController.swift): `ClashX/ViewControllers/ExternalControlViewController.swift`

### Configuration

- [Config state](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConfigManager.swift): `ClashX/General/Managers/ConfigManager.swift`
- [Config files](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConfigFileManager.swift): `ClashX/General/Managers/ConfigFileManager.swift`
- [Config model](https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/ClashConfig.swift): `ClashX/Models/ClashConfig.swift`
- [Remote profiles](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/RemoteConfigManager.swift): `ClashX/General/Managers/RemoteConfigManager.swift`
- [Remote profile model](https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/RemoteConfigModel.swift): `ClashX/Models/RemoteConfigModel.swift`
- [Saved selections](https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/SavedProxyModel.swift): `ClashX/Models/SavedProxyModel.swift`

### Proxy control

- [Proxy models](https://github.com/ladybug-w/clashx/blob/master/ClashX/Models/ClashProxy.swift): `ClashX/Models/ClashProxy.swift`
- [Proxy menu factory](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/MenuItemFactory.swift): `ClashX/General/Managers/MenuItemFactory.swift`
- [Proxy menu items](https://github.com/ladybug-w/clashx/blob/master/ClashX/Views/ProxyMenuItem.swift): `ClashX/Views/ProxyMenuItem.swift`
- [Remote control](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/RemoteControlManager.swift): `ClashX/General/Managers/RemoteControlManager.swift`
- [System proxy manager](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/SystemProxyManager.swift): `ClashX/General/Managers/SystemProxyManager.swift`
- [Privileged helper client](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/PrivilegedHelperManager.swift): `ClashX/General/Managers/PrivilegedHelperManager.swift`
- [Proxy helper protocol](https://github.com/ladybug-w/clashx/blob/master/ProxyConfigHelper/ProxyConfigRemoteProcessProtocol.h): `ProxyConfigHelper/ProxyConfigRemoteProcessProtocol.h`

### Runtime services

- [Clash core](https://github.com/ladybug-w/clashx/blob/master/ClashX/goClash/main.go): `ClashX/goClash/main.go`
- [Core API client](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/ApiRequest.swift): `ClashX/General/ApiRequest.swift`
- [Connection status](https://github.com/ladybug-w/clashx/blob/master/ClashX/General/Managers/ConnectionManager.swift): `ClashX/General/Managers/ConnectionManager.swift`
- [Logging](https://github.com/ladybug-w/clashx/blob/master/ClashX/Basic/Logger.swift): `ClashX/Basic/Logger.swift`

### Other components

- **Mac user**

## Connections

- Mac user → App coordinator: launches
- App coordinator → Status menu: creates (evidence: `ClashX/AppDelegate.swift`)
- App coordinator → Config files: copies sample (evidence: `ClashX/AppDelegate.swift`)
- App coordinator → Config state: starts proxy (evidence: `ClashX/AppDelegate.swift`)
- App coordinator → Remote profiles: coordinates (evidence: `ClashX/AppDelegate.swift`)
- App coordinator → System proxy manager: configures menu (evidence: `ClashX/AppDelegate.swift`)
- App coordinator → Connection status: adds menu option (evidence: `ClashX/AppDelegate.swift`)
- Config state → Config files: watches files (evidence: `ClashX/General/Managers/ConfigManager.swift`)
- Config state → Config model: holds current (evidence: `ClashX/General/Managers/ConfigManager.swift`)
- Config state → Saved selections: persists selections (evidence: `ClashX/General/Managers/ConfigManager.swift`)
- Remote profiles → Remote profile model: uses model (evidence: `ClashX/General/Managers/RemoteConfigManager.swift`)
- Remote profiles → Config state: updates state (evidence: `ClashX/General/Managers/RemoteConfigManager.swift`)
- External control UI → Remote control: controls (evidence: `ClashX/ViewControllers/ExternalControlViewController.swift`)
- Remote control → Config state: sets API override (evidence: `ClashX/General/Managers/RemoteControlManager.swift`)
- Remote control → Proxy menu factory: recreates menus (evidence: `ClashX/General/Managers/RemoteControlManager.swift`)
- Proxy menu factory → Core API client: requests proxy data (evidence: `ClashX/General/Managers/MenuItemFactory.swift`)
- Proxy menu factory → Proxy models: builds menus from (evidence: `ClashX/General/Managers/MenuItemFactory.swift`)
- Proxy menu factory → Proxy menu items: creates items (evidence: `ClashX/General/Managers/MenuItemFactory.swift`)
- Proxy menu items → Proxy models: displays (evidence: `ClashX/Views/ProxyMenuItem.swift`)
- Connection status → Core API client: requests status (evidence: `ClashX/General/Managers/ConnectionManager.swift`)
- Core API client → Config model: decodes config (evidence: `ClashX/General/ApiRequest.swift`)
- Dashboard web view → Core API client: uses API
- App coordinator → Clash core: starts core
- Core API client → Clash core: calls core API
- System proxy manager → Config state: reads ports (evidence: `ClashX/General/Managers/SystemProxyManager.swift`)
- System proxy manager → Privileged helper client: requests proxy changes (evidence: `ClashX/General/Managers/SystemProxyManager.swift`)
- Privileged helper client → Proxy helper protocol: uses protocol
- Privileged helper client → Logging: logs operations (evidence: `ClashX/General/Managers/PrivilegedHelperManager.swift`)
