# nikkinikki-org/openwrt-momo architecture

> Architecture diagram of the GitHub repository nikkinikki-org/openwrt-momo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikkinikki-org/openwrt-momo
- Repository: https://github.com/nikkinikki-org/openwrt-momo

## Overview

1. **What this repo is**
   - This is an OpenWrt package repository for **Momo**, a transparent proxy solution built around **sing-box**.
   - It is split into two installable packages: the core runtime package **`momo`** and the LuCI web UI package **`luci-app-momo`**.

2. **High-level architecture**
   - The system has a **control plane** and a **data plane**.
   - The control plane is the LuCI app plus OpenWrt config/init scripts.
   - The data plane is the runtime proxy process (**sing-box**) plus firewall and routing rules that intercept traffic and steer it into the proxy.

3. **Core runtime package: `momo/`**
   - `momo` contains the service-side OpenWrt package metadata and runtime assets.
   - Key files include:
     - `momo.init` for service startup and lifecycle
     - `momo.conf` for default config
     - `momo.upgrade` for upgrade handling
     - `uci-defaults/*` for first-run setup and migrations
   - This package is responsible for turning config into an active proxy/routing setup on the router.

4. **Proxy orchestration and routing**
   - The README describes the runtime sequence: start sing-box, read profile parameters, set IP rules/routes, then generate and apply firewall rules.
   - That implies Momo is not just a proxy launcher; it also owns **policy routing** and **traffic interception** setup.
   - Supported modes include **Redirect**, **TPROXY**, and **TUN**, with IPv4 and IPv6 coverage.

5. **Firewall and kernel integration**
   - The repo explicitly targets **OpenWrt firewall4** and Linux kernel features needed for packet interception.
   - Under `momo/files/firewall/` are nftables fragments such as `geoip_cn.nft` and `geoip6_cn.nft`, indicating country-based routing/filtering support.
   - Dependencies like `kmod-nft-tproxy`, `kmod-nft-socket`, `kmod-tun`, and `ip-full` show the architecture depends on kernel networking primitives, not just user-space proxying.

6. **Configuration generation and templating**
   - The `momo/files/ucode/` directory contains `.uc`/`.ut` files such as `mixin.uc`, `include.uc`, and `hijack.ut`.
   - These are used to generate or compose configuration logic for the service, especially for reusable routing/firewall/profile behavior.
   - This suggests a template-driven pipeline: **UCI config + ucode templates → generated runtime config/firewall rules**.

7. **LuCI web UI package: `luci-app-momo/`**
   - `luci-app-momo` provides the web interface for configuring and observing Momo in LuCI.
   - The main view modules are:
     - `app.js` for overall app settings
     - `proxy.js` for proxy mode/configuration
     - `profile.js` for profile management
     - `editor.js` for editing config/profile content
     - `log.js` for log viewing
     - `mixin.js` for shared UI logic
   - This UI is the operator-facing boundary into the backend service.

8. **LuCI-to-backend boundary**
   - `luci-app-momo/root/usr/share/luci/menu.d/` defines how the app appears in LuCI.
   - `rpcd/acl.d/` defines permissions for accessing service data and configuration through OpenWrt’s RPC layer.
   - `rpcd/ucode/luci.momo` is the bridge that likely exposes backend state/configuration to the UI.
   - In architecture terms, LuCI does not run the proxy; it calls into OpenWrt’s config/RPC interfaces to control it.

9. **Shared resource and data model**
   - The repo is centered around **OpenWrt UCI configuration** as the persistent source of truth.
   - Profiles, proxy settings, restart scheduling, and access control are all presented as configurable state, then converted into runtime behavior by the backend.
   - The `po/` directories show the UI is localized, with templates plus Chinese translations.

10. **External runtime dependencies**
   - The repo depends on **sing-box >= 1.12** as the actual proxy engine.
   - It also relies on OpenWrt system tools and libraries such as `curl`, `ca-bundle`, `firewall4`, and `ip-full`.
   - The architecture assumes OpenWrt **24.10+** and kernel **5.13+**, because those versions provide the networking and firewall capabilities needed for transparent proxying.

11. **Install/build/deploy pipeline**
   - This is packaged as an OpenWrt feed with build scripts and GitHub Actions for package builds/releases.
   - `feed.sh`, `install.sh`, and `uninstall.sh` are deployment helpers for adding/removing the feed or release packages.
   - The CI workflows under `.github/workflows/` automate package build, release publication, stale issue handling, and cleanup.

12. **Operational behavior**
   - The README’s “How does it work” sequence maps directly to the system design:
     1) run sing-box  
     2) optionally schedule restarts  
     3) read profile parameters  
     4) apply policy routing  
     5) generate/apply firewall rules
   - So the main flow is: **user configures in LuCI → config stored in UCI → backend generates routing/firewall/proxy state → router transparently intercepts traffic and forwards it through sing-box**.

Main entry points: [`momo/Makefile`](https://github.com/nikkinikki-org/openwrt-momo/tree/main/momo/Makefile) (momo), [`luci-app-momo/Makefile`](https://github.com/nikkinikki-org/openwrt-momo/tree/main/luci-app-momo/Makefile) (luci-app-momo), [`momo/files/ucode/mixin.uc`](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/ucode/mixin.uc) (Templates), [`luci-app-momo/root/usr/share/rpcd/ucode/luci.momo`](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/rpcd/ucode/luci.momo) (RPC bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_control["Control plane"]
  node_luci_app["luci-app-momo<br/>LuCI package"]
  node_ui_views["UI views<br/>LuCI views<br/>[app.js]"]
  node_ui_tools["UI helpers<br/>shared JS<br/>[momo.js]"]
  node_luci_menu["LuCI menu<br/>menu definition<br/>[luci-app-momo.json]"]
  node_rpc_bridge["RPC bridge<br/>rpcd ucode<br/>[luci.momo]"]
  node_acl["ACL<br/>rpc permissions<br/>[luci-app-momo.json]"]
  node_i18n["Translations<br/>localization<br/>[momo.pot]"]
end

subgraph group_group_runtime["Runtime package"]
  node_momo_pkg["momo<br/>core package"]
  node_momo_init["Startup<br/>init script<br/>[momo.init]"]
  node_momo_conf["Defaults<br/>default config<br/>[momo.conf]"]
  node_momo_upgrade["Upgrade<br/>[momo.upgrade]"]
  node_uci_defaults["First-run<br/>uci defaults<br/>[init.sh]"]
  node_ucode_tpl["Templates<br/>[mixin.uc]"]
end

subgraph group_group_dataplane["Data plane"]
  node_firewall_rules["Firewall rules<br/>nftables fragments<br/>[geoip_cn.nft]"]
  node_sing_box["sing-box<br/>proxy engine"]
  node_policy_routing["Policy routing<br/>routing control"]
  node_interception_modes["Intercept modes<br/>traffic capture"]
  node_kernel_deps{{"Kernel deps<br/>netfilter modules"}}
end

subgraph group_group_delivery["Delivery"]
  node_build_ci["Build & release<br/>GitHub Actions<br/>[build-packages.yml]"]
  node_feed_scripts["Feed scripts<br/>deploy helpers<br/>[feed.sh]"]
end

node_repo["openwrt-momo<br/>OpenWrt feed"]

node_repo -->|"contains"| node_momo_pkg
node_repo -->|"contains"| node_luci_app
node_repo -->|"automates"| node_build_ci
node_repo -->|"ships"| node_feed_scripts
node_momo_pkg -->|"boots"| node_momo_init
node_momo_pkg -->|"defaults"| node_momo_conf
node_momo_pkg -->|"migrates"| node_momo_upgrade
node_momo_pkg -->|"initializes"| node_uci_defaults
node_momo_pkg -->|"generates"| node_ucode_tpl
node_momo_pkg -->|"installs"| node_firewall_rules
node_ucode_tpl -->|"builds"| node_policy_routing
node_ucode_tpl -->|"selects"| node_interception_modes
node_firewall_rules -->|"depends on"| node_kernel_deps
node_policy_routing -->|"steers traffic to"| node_sing_box
node_interception_modes -->|"requires"| node_kernel_deps
node_luci_app -->|"implements"| node_ui_views
node_luci_app -->|"shares logic"| node_ui_tools
node_luci_app -->|"registers"| node_luci_menu
node_luci_app -->|"calls"| node_rpc_bridge
node_luci_app -->|"authorized by"| node_acl
node_luci_app -->|"localizes"| node_i18n
node_rpc_bridge -->|"reads state from"| node_momo_pkg

click node_momo_pkg "https://github.com/nikkinikki-org/openwrt-momo/tree/main/momo/Makefile"
click node_momo_init "https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/momo.init"
click node_momo_conf "https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/momo.conf"
click node_momo_upgrade "https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/momo.upgrade"
click node_uci_defaults "https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/uci-defaults/init.sh"
click node_ucode_tpl "https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/ucode/mixin.uc"
click node_firewall_rules "https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/firewall/geoip_cn.nft"
click node_luci_app "https://github.com/nikkinikki-org/openwrt-momo/tree/main/luci-app-momo/Makefile"
click node_ui_views "https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/htdocs/luci-static/resources/view/momo/app.js"
click node_ui_tools "https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/htdocs/luci-static/resources/tools/momo.js"
click node_luci_menu "https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/luci/menu.d/luci-app-momo.json"
click node_rpc_bridge "https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/rpcd/ucode/luci.momo"
click node_acl "https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/rpcd/acl.d/luci-app-momo.json"
click node_i18n "https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/po/templates/momo.pot"
click node_build_ci "https://github.com/nikkinikki-org/openwrt-momo/blob/main/.github/workflows/build-packages.yml"
click node_feed_scripts "https://github.com/nikkinikki-org/openwrt-momo/blob/main/feed.sh"

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_app,node_ui_views,node_ui_tools,node_luci_menu,node_rpc_bridge,node_acl,node_i18n toneBlue
class node_momo_pkg,node_momo_init,node_momo_conf,node_momo_upgrade,node_uci_defaults,node_ucode_tpl toneAmber
class node_firewall_rules,node_sing_box,node_policy_routing,node_interception_modes,node_kernel_deps toneMint
class node_build_ci,node_feed_scripts toneRose
class node_repo toneNeutral
```

## Components

### Control plane

LuCI UI and RPC/config boundary used to operate Momo.

- [luci-app-momo](https://github.com/nikkinikki-org/openwrt-momo/tree/main/luci-app-momo/Makefile): LuCI package · Operator-facing web UI for configuring and observing Momo. · `luci-app-momo/Makefile`
- [UI views](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/htdocs/luci-static/resources/view/momo/app.js): LuCI views · Main configuration and status screens for app, proxy, profile, editor, and logs. · `luci-app-momo/htdocs/luci-static/resources/view/momo/app.js`
- [UI helpers](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/htdocs/luci-static/resources/tools/momo.js): shared JS · Reusable front-end helper code shared by the LuCI views. · `luci-app-momo/htdocs/luci-static/resources/tools/momo.js`
- [LuCI menu](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/luci/menu.d/luci-app-momo.json): menu definition · Registers the package in the LuCI navigation tree. · `luci-app-momo/root/usr/share/luci/menu.d/luci-app-momo.json`
- [RPC bridge](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/rpcd/ucode/luci.momo): rpcd ucode · Exposes backend state and config to the LuCI UI through OpenWrt RPC. · `luci-app-momo/root/usr/share/rpcd/ucode/luci.momo`
- [ACL](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/root/usr/share/rpcd/acl.d/luci-app-momo.json): rpc permissions · Defines UI permissions for accessing Momo service data and configuration. · `luci-app-momo/root/usr/share/rpcd/acl.d/luci-app-momo.json`
- [Translations](https://github.com/nikkinikki-org/openwrt-momo/blob/main/luci-app-momo/po/templates/momo.pot): localization · User-facing strings and templates for multilingual LuCI views. · `luci-app-momo/po/templates/momo.pot`

### Runtime package

Core OpenWrt package that boots and maintains the transparent proxy service.

- [momo](https://github.com/nikkinikki-org/openwrt-momo/tree/main/momo/Makefile): core package · Service-side package that turns UCI config into active proxy and routing behavior. · `momo/Makefile`
- [Startup](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/momo.init): init script · Starts and supervises the Momo service lifecycle on OpenWrt. · `momo/files/momo.init`
- [Defaults](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/momo.conf): default config · Baseline package configuration and runtime defaults. · `momo/files/momo.conf`
- [Upgrade](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/momo.upgrade): upgrade hook · Handles package upgrade and migration behavior. · `momo/files/momo.upgrade`
- [First-run](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/uci-defaults/init.sh): uci defaults · Initial setup and migration scripts applied on install or upgrade. · `momo/files/uci-defaults/init.sh`
- [Templates](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/ucode/mixin.uc): ucode templates · Reusable ucode templates that compose config, profile, and hijack logic. · `momo/files/ucode/mixin.uc`

### Data plane

Proxy engine, routing, and firewall interception path used at runtime.

- [Firewall rules](https://github.com/nikkinikki-org/openwrt-momo/blob/main/momo/files/firewall/geoip_cn.nft): nftables fragments · Firewall4-compatible nft fragments for country-based routing and interception. · `momo/files/firewall/geoip_cn.nft`
- **sing-box**: proxy engine · External proxy runtime used for transparent forwarding.
- **Policy routing**: routing control · Applies IP rules and routes to steer selected traffic into the proxy path.
- **Intercept modes**: traffic capture · Redirect, TPROXY, and TUN-based packet interception paths.
- **Kernel deps**: netfilter modules · Kernel features used for socket matching, tproxy, and tun-based interception.

### Delivery

Feed scripts and CI workflows for packaging and release automation.

- [Build & release](https://github.com/nikkinikki-org/openwrt-momo/blob/main/.github/workflows/build-packages.yml): GitHub Actions · Package build, release publication, and maintenance workflows. · `.github/workflows/build-packages.yml`
- [Feed scripts](https://github.com/nikkinikki-org/openwrt-momo/blob/main/feed.sh): deploy helpers · Shell helpers for installing, updating, and removing the feed or packages. · `feed.sh`

### Other components

- **openwrt-momo**: OpenWrt feed · Package repository for Momo, split into runtime and LuCI UI packages.

## Connections

- openwrt-momo → momo: contains · Repository includes the core runtime package.
- openwrt-momo → luci-app-momo: contains · Repository includes the LuCI frontend package.
- openwrt-momo → Build & release: automates · CI workflows build and release packages.
- openwrt-momo → Feed scripts: ships · Top-level scripts support feed and package deployment.
- momo → Startup: boots · Package startup logic is defined by the init script.
- momo → Defaults: defaults · Package behavior is seeded by default config.
- momo → Upgrade: migrates · Upgrade hook preserves or transforms state across versions.
- momo → First-run: initializes · UCI defaults handle first-run setup and migrations.
- momo → Templates: generates · Ucode templates compose runtime config and rules.
- momo → Firewall rules: installs · Runtime package provides nftables rule fragments.
- Templates → Policy routing: builds · Templates generate routing and service control behavior.
- Templates → Intercept modes: selects · Templates support the different transparent proxy modes.
- Firewall rules → Kernel deps: depends on · Firewall interception requires kernel netfilter features.
- Policy routing → sing-box: steers traffic to · Policy routing directs traffic into the proxy engine.
- Intercept modes → Kernel deps: requires · Redirect, TPROXY, and TUN rely on kernel primitives.
- luci-app-momo → UI views: implements · Main configuration and status screens live in the view modules.
- luci-app-momo → UI helpers: shares logic · Common UI behavior is factored into helper code.
- luci-app-momo → LuCI menu: registers · LuCI menu definition exposes the app in navigation.
- luci-app-momo → RPC bridge: calls · UI talks to backend state through rpcd ucode.
- luci-app-momo → ACL: authorized by · RPC access is constrained by ACL definitions.
- luci-app-momo → Translations: localizes · View text is translated through PO templates and language files.
- RPC bridge → momo: reads state from · The bridge surfaces backend config and runtime information.