secubox-openwrt/.codex/architecture.md

Architecture

High-Level View

The SecuBox suite is a collection of LuCI packages that all share the same pattern:

1. LuCI Views (htdocs/luci-static/resources/view/<module>/*.js) build the UI using view.extend, ui, and DOM helpers. Views import per-module API helpers and shared CSS (system-hub/common.css, plus module-specific .css).
2. API Helpers (htdocs/luci-static/resources/<module>/api.js) declare ubus calls with rpc.declare and export a baseclass.extend instance that exposes typed methods (getStatus, listServices, etc.).
3. RPCD Backend (root/usr/libexec/rpcd/luci.<module>) receives list/call requests from ubus, executes shell or UCI logic, and emits JSON via json_* helpers.
4. Navigation & ACL (root/usr/share/luci/menu.d/*.json, root/usr/share/rpcd/acl.d/*.json) describe where the module appears in LuCI and who may access each ubus method.
5. Deployment Tooling (deploy-module-template.sh, secubox-tools/*.sh) automates copying files to routers, backing up, fixing permissions, clearing caches, and restarting rpcd/uhttpd.

System Hub and SecuBox provide “umbrella” tabs (admin/secubox/...) but each module is otherwise isolated and should not reach into another module's files unless explicitly documented (e.g., System Hub reading SecuBox theme preferences via luci.secubox get_theme).

Data Flow

1. User opens admin/secubox/.../<tab> in LuCI.
2. Menu JSON loads luci-static/resources/view/<module>/<view>.js.
3. The view's load() issues Promise.all([...API calls...]) to api.js helpers.
4. api.js uses rpc.declare({object: 'luci.<module>', method: ...}) to talk to ubus.
5. ubus dispatches to /usr/libexec/rpcd/luci.<module>, which handles list/call requests, touches UCI/system services, and replies JSON.
6. View render() updates DOM components, sets up poll.add for periodic refresh, and attaches event handlers that call more RPC actions.
7. Deploy scripts copy updated JS/CSS/RPC/menu/ACL to the router, fix permissions, and restart rpcd/uhttpd to expose the changes.

Boundaries & Dependency Rules

• Modules must keep JS, CSS, RPC, menu, and ACL files self-contained under their own directory; shared assets go in system-hub/common.css or templates/.
• Do not import code from another module's htdocs/.../view folder. Shared logic should be duplicated intentionally or moved into a common helper under system-hub/ or a new shared location documented in DEVELOPMENT-GUIDELINES.md.
• Any ubus interaction between modules must be explicitly documented (e.g., System Hub calling luci.secubox get_theme). Otherwise, treat every luci.<module> namespace as private.
• Keep RPCD scripts shell-only unless the repo adds other interpreters; they must rely on standard OpenWrt utilities (ubus, uci, /lib/functions.sh, /usr/share/libubox/jshn.sh).

Adding a New Module – Checklist

1. Scaffold: Copy templates/luci-app-template or an existing module directory and rename files (PKG_NAME, LUCI_TITLE, etc.).
2. Implement RPCD: Create /root/usr/libexec/rpcd/luci.<module> with list/call, JSON helpers, and method coverage for every UI action.
3. Add API Helper: In htdocs/luci-static/resources/<module>/api.js extend baseclass and declare each ubus call.
4. Build Views: Under htdocs/luci-static/resources/view/<module>/ add overview.js plus additional tabs as needed. Include CSS via <link> to system-hub/common.css and module-specific files. Follow design system rules.
5. Wire Menu/ACL: Create root/usr/share/luci/menu.d/luci-app-<module>.json with the correct admin/secubox/... path and firstchild entry; create root/usr/share/rpcd/acl.d/luci-app-<module>.json enumerating read/write ubus methods.
6. Docs: Write luci-app-<module>/README.md describing purpose, features, install commands, and troubleshooting steps.
7. Permissions: Update Makefile with PKG_FILE_MODES:=/usr/libexec/rpcd/luci.<module>:755 (and any other executables). Confirm CSS/JS remain 644.
8. Validation & Build: Run ./secubox-tools/fix-permissions.sh --local, ./secubox-tools/validate-module-generation.sh luci-app-<module>, and ./secubox-tools/local-build.sh build luci-app-<module> before submitting.