# itdoginfo/podkop architecture

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

- Interactive diagram: https://gitdiagram.com/itdoginfo/podkop
- Repository: https://github.com/itdoginfo/podkop

## Overview

#### Purpose and Deployment
Podkop is an OpenWrt 24.10+ traffic-routing package built around sing-box. It routes selected resources through a tunnel while leaving other traffic direct, and modifies Dnsmasq and sing-box configuration at service startup. Packaging targets both APK and IPK ecosystems: `podkop/Makefile`, `luci-app-podkop/Makefile`, `install.sh`.

#### Runtime Entry Points
The device-side service entry point is the init script `podkop/files/etc/init.d/podkop`, which invokes the operational shell program `podkop/files/usr/bin/podkop`. Default persistent configuration is UCI-backed at `podkop/files/etc/config/podkop`. The LuCI package registers its UI/menu and RPC permissions through `luci-app-podkop/root/usr/share/luci/menu.d/luci-app-podkop.json` and `luci-app-podkop/root/usr/share/rpcd/acl.d/luci-app-podkop.json`.

#### Routing and Configuration Core
The shell runtime owns system integration: nftables manipulation, routing rulesets, logging, and sing-box configuration generation/management. Its key boundaries are:
- Service orchestration: `podkop/files/usr/bin/podkop`, `podkop/files/etc/init.d/podkop`
- Firewall/ruleset layer: `podkop/files/usr/lib/nft.sh`, `podkop/files/usr/lib/rulesets.sh`
- sing-box adapter layer: `podkop/files/usr/lib/sing_box_config_facade.sh`, `podkop/files/usr/lib/sing_box_config_manager.sh`

UCI configuration feeds this runtime; the runtime materializes/updates sing-box and networking state rather than exposing those internals directly to the UI.

#### LuCI Frontend Architecture
`fe-app-podkop` is a TypeScript frontend compiled and shipped into the LuCI app’s static views. Its bootstrap is `fe-app-podkop/src/main.ts`; domain composition and remote calls are centered in `fe-app-podkop/src/podkop/index.ts` and `fe-app-podkop/src/podkop/api.ts`. The checked-in LuCI view entrypoints include `luci-app-podkop/htdocs/luci-static/resources/view/podkop/main.js`, `luci-app-podkop/htdocs/luci-static/resources/view/podkop/dashboard.js`, and `luci-app-podkop/htdocs/luci-static/resources/view/podkop/diagnostic.js`.

The frontend operates in the LuCI browser runtime, using LuCI/RPC interfaces and shell-backed methods rather than a separate web server.

#### UI State, Services, and Live Data
Frontend services separate tab selection, local state, core lifecycle calls, logging, and socket/event handling:
`fe-app-podkop/src/podkop/services/core.service.ts`,
`fe-app-podkop/src/podkop/services/store.service.ts`,
`fe-app-podkop/src/podkop/services/socket.service.ts`.

Data flows from API/fetcher and custom/shell method layers into stores and tab controllers:
`fe-app-podkop/src/podkop/fetchers/fetchServicesInfo.ts`,
`fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts`,
`fe-app-podkop/src/podkop/methods/custom/getConfigSections.ts`.
This is the primary UI-to-router control boundary.

#### Dashboard and Diagnostics
The dashboard renders service/configuration-oriented sections and widgets, with its controller coordinating load/update behavior: `fe-app-podkop/src/podkop/tabs/dashboard/initController.ts`, `fe-app-podkop/src/podkop/tabs/dashboard/render.ts`.

Diagnostics is a distinct staged check system with stored results and executable checks for DNS, FakeIP, nftables, configuration sections, and sing-box: `fe-app-podkop/src/podkop/tabs/diagnostic/diagnostic.store.ts`, `fe-app-podkop/src/podkop/tabs/diagnostic/checks/runNftCheck.ts`, `fe-app-podkop/src/podkop/tabs/diagnostic/checks/runSingBoxCheck.ts`.

#### External Dependencies and Constraints
Material dependencies are OpenWrt/LuCI, UCI, rpcd, Dnsmasq, nftables, and sing-box; the dashboard also depends on sing-box’s Clash API and is documented as HTTP-only. Release/build infrastructure includes package Dockerfiles (`Dockerfile-apk`, `Dockerfile-ipk`) and SDK variants under `sdk/`.

Main entry points: [`podkop/files/usr/bin/podkop`](https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/bin/podkop) (Podkop runtime), [`fe-app-podkop/src/podkop/api.ts`](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/api.ts) (UI API layer), [`fe-app-podkop/src/podkop/services/core.service.ts`](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/services/core.service.ts) (UI services and state), [`fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts`](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts) (rpcd / shell methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_luci["LuCI frontend"]
  node_luci_entries["LuCI view entrypoints<br/>browser views<br/>[main.js]"]
  node_frontend_bootstrap["frontend bootstrap<br/>TypeScript entry<br/>[main.ts]"]
  node_frontend_api["UI API layer<br/>domain and RPC API<br/>[api.ts]"]
  node_ui_services["UI services and state<br/>lifecycle/store/socket<br/>[core.service.ts]"]
  node_dashboard["dashboard controller<br/>dashboard tab<br/>[initController.ts]"]
  node_diagnostics["diagnostic checks<br/>staged checks"]
  node_rpc_acl["rpcd permissions<br/>RPC ACL"]
end

subgraph group_device["OpenWrt service"]
  node_init["procd init entry<br/>init script<br/>[podkop]"]
  node_runtime["Podkop runtime<br/>shell orchestrator"]
  node_uci["Podkop UCI config<br/>persistent config"]
end

subgraph group_routing["Routing engine"]
  node_nft["nftables layer<br/>firewall scripts<br/>[nft.sh]"]
  node_rulesets["routing rulesets<br/>ruleset scripts<br/>[rulesets.sh]"]
  node_singbox_facade["sing-box facade<br/>config adapter"]
  node_singbox_manager["sing-box manager<br/>config generator"]
end

subgraph group_build["Packaging"]
  node_package["OpenWrt package<br/>APK/IPK build recipe"]
  node_luci_package["LuCI package<br/>LuCI build recipe"]
end

node_singbox{{"sing-box<br/>traffic proxy"}}
node_dnsmasq{{"Dnsmasq<br/>DNS service"}}
node_rpcd{{"rpcd / shell methods<br/>OpenWrt RPC boundary<br/>[callBaseMethod.ts]"}}
node_clash_api{{"Clash API<br/>sing-box HTTP API"}}

node_init -->|"invokes"| node_runtime
node_uci -->|"configures"| node_runtime
node_runtime -->|"manages"| node_nft
node_runtime -->|"installs"| node_rulesets
node_runtime -->|"uses"| node_singbox_facade
node_singbox_facade -->|"delegates config"| node_singbox_manager
node_singbox_manager -->|"configures"| node_singbox
node_runtime -->|"updates DNS integration"| node_dnsmasq
node_luci_entries -->|"loads"| node_frontend_bootstrap
node_frontend_bootstrap -->|"initializes"| node_frontend_api
node_frontend_api -->|"feeds"| node_ui_services
node_ui_services -->|"drives"| node_dashboard
node_ui_services -->|"drives"| node_diagnostics
node_frontend_api -->|"RPC calls"| node_rpcd
node_rpc_acl -->|"authorizes"| node_rpcd
node_rpcd -->|"shell-backed control"| node_runtime
node_dashboard -->|"live status"| node_clash_api
node_clash_api -->|"served by"| node_singbox
node_package -.->|"packages"| node_runtime
node_luci_package -.->|"ships"| node_luci_entries
node_luci_package -.->|"ships"| node_rpc_acl

click node_init "https://github.com/itdoginfo/podkop/blob/main/podkop/files/etc/init.d/podkop"
click node_runtime "https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/bin/podkop"
click node_uci "https://github.com/itdoginfo/podkop/blob/main/podkop/files/etc/config/podkop"
click node_nft "https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/nft.sh"
click node_rulesets "https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/rulesets.sh"
click node_singbox_facade "https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/sing_box_config_facade.sh"
click node_singbox_manager "https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/sing_box_config_manager.sh"
click node_luci_entries "https://github.com/itdoginfo/podkop/blob/main/luci-app-podkop/htdocs/luci-static/resources/view/podkop/main.js"
click node_frontend_bootstrap "https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/main.ts"
click node_frontend_api "https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/api.ts"
click node_ui_services "https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/services/core.service.ts"
click node_dashboard "https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/tabs/dashboard/initController.ts"
click node_diagnostics "https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/tabs/diagnostic/diagnostic.store.ts"
click node_rpc_acl "https://github.com/itdoginfo/podkop/blob/main/luci-app-podkop/root/usr/share/rpcd/acl.d/luci-app-podkop.json"
click node_rpcd "https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts"
click node_package "https://github.com/itdoginfo/podkop/blob/main/podkop/Makefile"
click node_luci_package "https://github.com/itdoginfo/podkop/blob/main/luci-app-podkop/Makefile"

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_entries,node_frontend_bootstrap,node_frontend_api,node_ui_services,node_dashboard,node_diagnostics,node_rpc_acl toneBlue
class node_init,node_runtime,node_uci toneAmber
class node_nft,node_rulesets,node_singbox_facade,node_singbox_manager toneMint
class node_package,node_luci_package toneRose
class node_singbox,node_dnsmasq,node_rpcd,node_clash_api toneNeutral
```

## Components

### LuCI frontend

- [LuCI view entrypoints](https://github.com/itdoginfo/podkop/blob/main/luci-app-podkop/htdocs/luci-static/resources/view/podkop/main.js): browser views · Main, dashboard, and diagnostic view modules. · `luci-app-podkop/htdocs/luci-static/resources/view/podkop/main.js`
- [frontend bootstrap](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/main.ts): TypeScript entry · `fe-app-podkop/src/main.ts`
- [UI API layer](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/api.ts): domain and RPC API · Composes Podkop UI behavior and remote calls. · `fe-app-podkop/src/podkop/api.ts`
- [UI services and state](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/services/core.service.ts): lifecycle/store/socket · Coordinates lifecycle calls, local state, and events. · `fe-app-podkop/src/podkop/services/core.service.ts`
- [dashboard controller](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/tabs/dashboard/initController.ts): dashboard tab · Loads and updates service and configuration widgets. · `fe-app-podkop/src/podkop/tabs/dashboard/initController.ts`
- [diagnostic checks](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/tabs/diagnostic/diagnostic.store.ts): staged checks · Runs and stores DNS, FakeIP, nftables, config, and sing-box checks. · `fe-app-podkop/src/podkop/tabs/diagnostic/diagnostic.store.ts`
- [rpcd permissions](https://github.com/itdoginfo/podkop/blob/main/luci-app-podkop/root/usr/share/rpcd/acl.d/luci-app-podkop.json): RPC ACL · `luci-app-podkop/root/usr/share/rpcd/acl.d/luci-app-podkop.json`

### OpenWrt service

- [procd init entry](https://github.com/itdoginfo/podkop/blob/main/podkop/files/etc/init.d/podkop): init script · Starts and stops the device service. · `podkop/files/etc/init.d/podkop`
- [Podkop runtime](https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/bin/podkop): shell orchestrator · Owns startup, networking integration, logging, and generated state. · `podkop/files/usr/bin/podkop`
- [Podkop UCI config](https://github.com/itdoginfo/podkop/blob/main/podkop/files/etc/config/podkop): persistent config · `podkop/files/etc/config/podkop`

### Routing engine

- [nftables layer](https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/nft.sh): firewall scripts · `podkop/files/usr/lib/nft.sh`
- [routing rulesets](https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/rulesets.sh): ruleset scripts · `podkop/files/usr/lib/rulesets.sh`
- [sing-box facade](https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/sing_box_config_facade.sh): config adapter · `podkop/files/usr/lib/sing_box_config_facade.sh`
- [sing-box manager](https://github.com/itdoginfo/podkop/blob/main/podkop/files/usr/lib/sing_box_config_manager.sh): config generator · Materializes and manages sing-box configuration. · `podkop/files/usr/lib/sing_box_config_manager.sh`

### Packaging

- [OpenWrt package](https://github.com/itdoginfo/podkop/blob/main/podkop/Makefile): APK/IPK build recipe · Builds device-side package artifacts. · `podkop/Makefile`
- [LuCI package](https://github.com/itdoginfo/podkop/blob/main/luci-app-podkop/Makefile): LuCI build recipe · `luci-app-podkop/Makefile`

### Other components

- **sing-box**: traffic proxy · Applies tunnel and direct-routing policy.
- **Dnsmasq**: DNS service
- [rpcd / shell methods](https://github.com/itdoginfo/podkop/blob/main/fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts): OpenWrt RPC boundary · Exposes shell-backed router control to LuCI. · `fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts`
- **Clash API**: sing-box HTTP API · Dashboard live-data source; HTTP-only.

## Connections

- procd init entry → Podkop runtime: invokes
- Podkop UCI config → Podkop runtime: configures
- Podkop runtime → nftables layer: manages
- Podkop runtime → routing rulesets: installs
- Podkop runtime → sing-box facade: uses
- sing-box facade → sing-box manager: delegates config
- sing-box manager → sing-box: configures
- Podkop runtime → Dnsmasq: updates DNS integration
- LuCI view entrypoints → frontend bootstrap: loads
- frontend bootstrap → UI API layer: initializes
- UI API layer → UI services and state: feeds
- UI services and state → dashboard controller: drives
- UI services and state → diagnostic checks: drives
- UI API layer → rpcd / shell methods: RPC calls
- rpcd permissions → rpcd / shell methods: authorizes
- rpcd / shell methods → Podkop runtime: shell-backed control
- dashboard controller → Clash API: live status
- Clash API → sing-box: served by
- OpenWrt package → Podkop runtime: packages
- LuCI package → LuCI view entrypoints: ships
- LuCI package → rpcd permissions: ships