# vernesong/openclash architecture

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

## Overview

OpenClash is an OpenWrt LuCI client for managing the Mihomo proxy core. The principal workflow is an administrator using LuCI to import a subscription or configuration, select and start the core, then monitor it through status, logs, or a dashboard. Documented capabilities also include configuration editing and backup, core updates, access control, firewall modes, and modular overrides. The tree supports these subsystem paths, but most runtime wiring was not sampled; the graph therefore limits sourced relationships and marks the documented core integration separately.

Main entry points: [`luci-app-openclash/root/etc/openclash`](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/etc/openclash) (Mihomo core), [`luci-app-openclash/luasrc/model/cbi/openclash`](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/luasrc/model/cbi/openclash) (LuCI pages), [`luci-app-openclash/root/etc/init.d/openclash`](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/etc/init.d/openclash) (OpenClash service), [`luci-app-openclash/luasrc/controller/openclash.lua`](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/luasrc/controller/openclash.lua) (LuCI controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["LuCI interface"]
  node_luci["LuCI pages"]
  node_controller["LuCI controller<br/>[openclash.lua]"]
  node_status["Status interface<br/>[status.js]"]
end

subgraph group_config["Configuration"]
  node_editor["Config editor<br/>[config_edit.js]"]
  node_upload["Config and subscription<br/>[config_upload.js]"]
  node_yaml["YAML processing<br/>[YAML.rb]"]
  node_uci["UCI and overrides<br/>[uci.rb]"]
  node_configstore[("Router config files")]
  node_overrides["Override modules"]
end

subgraph group_runtime["Proxy runtime"]
  node_service["OpenClash service<br/>[openclash]"]
  node_runtime_scripts["Runtime scripts<br/>[openclash.sh]"]
  node_core["Mihomo core"]
  node_firewall["Firewall and access control<br/>[openclash.sh]"]
end

subgraph group_operations["Operations"]
  node_updates["Core and data updates"]
  node_logs["Logs and diagnostics<br/>[log.sh]"]
  node_guide["Setup guide<br/>[guide.js]"]
end

subgraph group_panels["Dashboards"]
  node_meta_panel["MetacubeXD panel"]
  node_zashboard["Zashboard panel"]
end

node_admin(("Router administrator"))
node_user_traffic(("Router traffic"))

node_admin -->|"configures"| node_luci
node_luci -.->|"imports config"| node_upload
node_luci -.->|"edits config"| node_editor
node_luci -.->|"manages core"| node_service
node_service -.->|"starts core"| node_core
node_admin -.->|"selects core"| node_core
node_status -->|"requests action"| node_controller
node_controller -.->|"dispatches"| node_service
node_user_traffic -.->|"is proxied"| node_core
node_core -.->|"uses modes"| node_firewall
node_admin -->|"customizes"| node_overrides
node_admin -->|"updates core"| node_updates
node_admin -.->|"checks diagnostics"| node_logs
node_admin -.->|"follows setup"| node_guide
node_core -.->|"serves dashboard"| node_meta_panel
node_core -.->|"serves dashboard"| node_zashboard

click node_luci "https://github.com/vernesong/openclash/tree/master/luci-app-openclash/luasrc/model/cbi/openclash"
click node_controller "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/luasrc/controller/openclash.lua"
click node_status "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/status.js"
click node_editor "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/config_edit.js"
click node_upload "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/config_upload.js"
click node_yaml "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/YAML.rb"
click node_uci "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/uci.rb"
click node_configstore "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/etc/config/openclash"
click node_service "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/etc/init.d/openclash"
click node_runtime_scripts "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash.sh"
click node_core "https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/etc/openclash"
click node_firewall "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash.sh"
click node_overrides "https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/etc/openclash/overwrite"
click node_updates "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash_update.sh"
click node_logs "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/log.sh"
click node_guide "https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/guide.js"
click node_meta_panel "https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/usr/share/openclash/ui/metacubexd"
click node_zashboard "https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/usr/share/openclash/ui/zashboard"

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_luci,node_controller,node_status toneBlue
class node_editor,node_upload,node_yaml,node_uci,node_configstore,node_overrides toneAmber
class node_service,node_runtime_scripts,node_core,node_firewall,node_admin,node_user_traffic toneMint
class node_updates,node_logs,node_guide toneRose
class node_meta_panel,node_zashboard toneIndigo
```

## Components

### LuCI interface

- [LuCI pages](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/luasrc/model/cbi/openclash): `luci-app-openclash/luasrc/model/cbi/openclash`
- [LuCI controller](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/luasrc/controller/openclash.lua): `luci-app-openclash/luasrc/controller/openclash.lua`
- [Status interface](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/status.js): `luci-app-openclash/root/www/luci-static/resources/openclash/js/status.js`

### Configuration

- [Config editor](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/config_edit.js): `luci-app-openclash/root/www/luci-static/resources/openclash/js/config_edit.js`
- [Config and subscription](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/config_upload.js): `luci-app-openclash/root/www/luci-static/resources/openclash/js/config_upload.js`
- [YAML processing](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/YAML.rb): `luci-app-openclash/root/usr/share/openclash/YAML.rb`
- [UCI and overrides](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/uci.rb): `luci-app-openclash/root/usr/share/openclash/uci.rb`
- [Router config files](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/etc/config/openclash): `luci-app-openclash/root/etc/config/openclash`
- [Override modules](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/etc/openclash/overwrite): `luci-app-openclash/root/etc/openclash/overwrite`

### Proxy runtime

- [OpenClash service](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/etc/init.d/openclash): `luci-app-openclash/root/etc/init.d/openclash`
- [Runtime scripts](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash.sh): `luci-app-openclash/root/usr/share/openclash/openclash.sh`
- [Mihomo core](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/etc/openclash): `luci-app-openclash/root/etc/openclash`
- [Firewall and access control](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash.sh): `luci-app-openclash/root/usr/share/openclash/openclash.sh`

### Operations

- [Core and data updates](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash_update.sh): `luci-app-openclash/root/usr/share/openclash/openclash_update.sh`
- [Logs and diagnostics](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/usr/share/openclash/log.sh): `luci-app-openclash/root/usr/share/openclash/log.sh`
- [Setup guide](https://github.com/vernesong/openclash/blob/master/luci-app-openclash/root/www/luci-static/resources/openclash/js/guide.js): `luci-app-openclash/root/www/luci-static/resources/openclash/js/guide.js`

### Dashboards

- [MetacubeXD panel](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/usr/share/openclash/ui/metacubexd): `luci-app-openclash/root/usr/share/openclash/ui/metacubexd`
- [Zashboard panel](https://github.com/vernesong/openclash/tree/master/luci-app-openclash/root/usr/share/openclash/ui/zashboard): `luci-app-openclash/root/usr/share/openclash/ui/zashboard`

### Other components

- **Router administrator**
- **Router traffic**

## Connections

- Router administrator → LuCI pages: configures (evidence: `README.md`)
- LuCI pages → Config and subscription: imports config
- LuCI pages → Config editor: edits config
- LuCI pages → OpenClash service: manages core
- OpenClash service → Mihomo core: starts core
- Router administrator → Mihomo core: selects core
- Status interface → LuCI controller: requests action (evidence: `luci-app-openclash/root/www/luci-static/resources/openclash/js/status.js`)
- LuCI controller → OpenClash service: dispatches
- Router traffic → Mihomo core: is proxied
- Mihomo core → Firewall and access control: uses modes
- Router administrator → Override modules: customizes (evidence: `README.md`)
- Router administrator → Core and data updates: updates core (evidence: `README.md`)
- Router administrator → Logs and diagnostics: checks diagnostics
- Router administrator → Setup guide: follows setup
- Mihomo core → MetacubeXD panel: serves dashboard
- Mihomo core → Zashboard panel: serves dashboard