CyberMind-FR
ce543762cc
Replace github.com/gkerma/secubox-openwrt with github.com/CyberMind-FR/secubox-openwrt across all files. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 line
444 KiB
JSON
1 line
444 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"SecuBox Documentation","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Project: OpenWrt LuCI Security & Management Suite</p> <p>Welcome to the SecuBox documentation! This comprehensive guide covers all aspects of developing, deploying, and maintaining SecuBox modules.</p>"},{"location":"#what-is-secubox","title":"\ud83c\udfd7\ufe0f What is SecuBox?","text":"<p>SecuBox is a comprehensive security and network management suite for OpenWrt consisting of 15 LuCI application modules that provide:</p> <ul> <li>Security Monitoring - CrowdSec intrusion prevention, Netdata metrics</li> <li>Network Intelligence - Deep packet inspection, traffic classification</li> <li>Access Control - Captive portal, authentication, VPN management</li> <li>Performance Optimization - QoS, bandwidth management, caching</li> <li>System Administration - Centralized dashboard, service management</li> </ul>"},{"location":"#quick-navigation","title":"\ud83d\ude80 Quick Navigation","text":"<ul> <li> <p>:fontawesome-solid-rocket:{ .lg .middle } Getting Started</p> <p>New to SecuBox? Start here!</p> <p>:octicons-arrow-right-24: Quick Start Guide</p> </li> <li> <p>:fontawesome-solid-book:{ .lg .middle } Development Guide</p> <p>Complete development reference with architecture diagrams</p> <p>:octicons-arrow-right-24: Development Guidelines</p> </li> <li> <p>:fontawesome-solid-code:{ .lg .middle } Code Templates</p> <p>Working examples and implementation patterns</p> <p>:octicons-arrow-right-24: Code Templates</p> </li> <li> <p>:fontawesome-solid-list-check:{ .lg .middle } Validation</p> <p>Module validation and testing workflows</p> <p>:octicons-arrow-right-24: Validation Guide</p> </li> </ul>"},{"location":"#15-module-suite","title":"\ud83d\udce6 15 Module Suite","text":""},{"location":"#core-control-2-modules","title":"Core Control (2 modules)","text":"<ul> <li>SecuBox Central Hub - Main dashboard and module management</li> <li>System Hub - System administration (health, services, logs, backup, etc.)</li> </ul>"},{"location":"#security-monitoring-2-modules","title":"Security & Monitoring (2 modules)","text":"<ul> <li>CrowdSec Dashboard - Intrusion prevention and threat intelligence</li> <li>Netdata Dashboard - Real-time system monitoring</li> </ul>"},{"location":"#network-intelligence-2-modules","title":"Network Intelligence (2 modules)","text":"<ul> <li>Netifyd Dashboard - Deep packet inspection and classification</li> <li>Network Modes - Network profile management</li> </ul>"},{"location":"#vpn-access-control-3-modules","title":"VPN & Access Control (3 modules)","text":"<ul> <li>WireGuard Dashboard - VPN tunnel management</li> <li>Client Guardian - Network access control and captive portal</li> <li>Auth Guardian - Authentication system</li> </ul>"},{"location":"#bandwidth-traffic-2-modules","title":"Bandwidth & Traffic (2 modules)","text":"<ul> <li>Bandwidth Manager - QoS and bandwidth quotas</li> <li>Traffic Shaper - Advanced traffic shaping</li> </ul>"},{"location":"#performance-services-2-modules","title":"Performance & Services (2 modules)","text":"<ul> <li>CDN Cache - Content delivery network proxy cache</li> <li>VHost Manager - Virtual host configuration</li> </ul>"},{"location":"#system-optimization-2-modules","title":"System Optimization (2 modules)","text":"<ul> <li>Media Flow - Media traffic optimization</li> <li>KSM Manager - Kernel same-page merging</li> </ul> <p>View Module Status \u2192</p>"},{"location":"#design-system","title":"\ud83c\udfa8 Design System","text":"<p>SecuBox uses a modern, consistent design system:</p> <ul> <li>Color Palette: Indigo/Violet gradients with dark mode support</li> <li>Typography: Inter (text) + JetBrains Mono (code/values)</li> <li>Components: Cards, badges, buttons with gradient effects</li> <li>Layout: Responsive grid system</li> </ul> <p>See the Design System section for complete specifications.</p>"},{"location":"#development-workflow","title":"\ud83d\udd27 Development Workflow","text":"<p>Critical Rules</p> <ol> <li>RPCD Naming: Script name must match ubus object (<code>luci.module-name</code>)</li> <li>Menu Paths: Must match view file locations exactly</li> <li>Permissions: 755 for RPCD scripts, 644 for CSS/JS</li> <li>Validation: Always run <code>./secubox-tools/validate-modules.sh</code> before commit</li> </ol>"},{"location":"#development-tools","title":"Development Tools","text":"<pre><code># Validate all modules (7 automated checks)\n./secubox-tools/validate-modules.sh\n\n# Fix file permissions automatically\n./secubox-tools/fix-permissions.sh --local\n\n# Build packages locally\n./secubox-tools/local-build.sh build luci-app-module-name\n</code></pre> <p>Complete Development Workflow \u2192</p>"},{"location":"#live-demo","title":"\ud83c\udf10 Live Demo","text":"<p>Experience SecuBox in action:</p> <p>Production Demo: https://secubox.cybermood.eu</p> <ul> <li>Main dashboard: <code>/</code></li> <li>System Hub: <code>/system-hub</code></li> <li>CrowdSec: <code>/crowdsec</code></li> <li>All 15 modules accessible</li> </ul>"},{"location":"#documentation-sections","title":"\ud83d\udcda Documentation Sections","text":""},{"location":"#for-new-contributors","title":"For New Contributors","text":"<ol> <li>Quick Start Guide - Essential rules and commands</li> <li>Development Guidelines - Complete reference</li> <li>CLAUDE.md - Build system and architecture</li> <li>Repository Guidelines - Structure, workflows, and PR expectations</li> </ol>"},{"location":"#for-ai-assisted-development","title":"For AI-Assisted Development","text":"<ol> <li>Module Implementation Guide - Step-by-step workflow</li> <li>Feature Regeneration Prompts - AI prompts for all modules</li> <li>Code Templates - Implementation patterns</li> </ol>"},{"location":"#support-resources","title":"\ud83d\udcde Support & Resources","text":"<ul> <li>GitHub Repository: gkerma/secubox-openwrt</li> <li>Documentation Issues: GitHub Issues</li> <li>Technical Support: support@cybermind.fr</li> <li>Company: CyberMind.fr</li> </ul>"},{"location":"#license","title":"\ud83d\udcdd License","text":"<p>Apache-2.0</p> <p>Last Updated: 2025-12-28 | Maintainer: CyberMind.fr</p>"},{"location":"claude/","title":"CLAUDE.md","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p> <p>This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.</p>"},{"location":"claude/#documentation-index","title":"\ud83d\udcda Documentation Index","text":"<p>IMPORTANT: Before working on any code, consult these guides:</p> <ol> <li>DEVELOPMENT-GUIDELINES.md - \u2b50 GUIDE COMPLET</li> <li>Design System & UI Guidelines (palettes, typographie, composants)</li> <li>Architecture & Naming Conventions (RPCD, menu paths, prefixes)</li> <li>RPCD & ubus Best Practices (erreurs communes, solutions)</li> <li>ACL & Permissions (templates, validations)</li> <li>JavaScript Patterns (API modules, views, event handling)</li> <li>CSS/Styling Standards (variables, responsive, dark mode)</li> <li>Common Errors & Solutions (diagnostics, fixes)</li> <li>Validation Checklist (pre-commit, pre-deploy, post-deploy)</li> <li> <p>Deployment Procedures (scripts, rollback, versioning)</p> </li> <li> <p>QUICK-START.md - \u26a1 AIDE-M\u00c9MOIRE RAPIDE</p> </li> <li>R\u00e8gles critiques (RPCD naming, menu paths, permissions)</li> <li>Design system essentials (couleurs, fonts, classes)</li> <li>Common commands (validation, build, deploy, debug)</li> <li>Quick code templates (RPCD, View, Headers, Cards)</li> <li> <p>Error quick fixes</p> </li> <li> <p>CLAUDE.md (ce fichier) - \ud83c\udfd7\ufe0f ARCHITECTURE & BUILD</p> </li> <li>Build commands (OpenWrt SDK, local build)</li> <li>Module structure (files, directories)</li> <li>CI/CD workflows</li> <li>Common issues techniques</li> </ol> <p>\u26a0\ufe0f R\u00c8GLES CRITIQUES \u00c0 TOUJOURS RESPECTER:</p> <ol> <li>RPCD Script Naming: Nom fichier = objet ubus (<code>luci.system-hub</code>)</li> <li>Menu Path Matching: Path menu = fichier vue (<code>system-hub/overview.js</code>)</li> <li>Permissions: RPCD = 755, CSS/JS = 644</li> <li>Auto-fix: <code>./secubox-tools/fix-permissions.sh --local</code> (avant commit)</li> <li>Auto-fix remote: <code>./secubox-tools/fix-permissions.sh --remote</code> (apr\u00e8s deploy)</li> <li>Validation: Toujours ex\u00e9cuter <code>./secubox-tools/validate-modules.sh</code> avant commit</li> <li>7 checks automatiques: RPCD naming, menu paths, view files, RPCD permissions, JSON syntax, ubus naming, htdocs permissions</li> <li>CSS Variables: Toujours utiliser <code>var(--sh-*)</code>, jamais hardcoder les couleurs</li> <li>Dark Mode: Toujours supporter dark mode avec <code>[data-theme=\"dark\"]</code></li> <li>Typography: Inter (texte), JetBrains Mono (valeurs num\u00e9riques)</li> <li>Gradient Effects: Utiliser <code>--sh-primary</code> \u2192 <code>--sh-primary-end</code> pour d\u00e9grad\u00e9s</li> </ol>"},{"location":"claude/#project-overview","title":"Project Overview","text":"<p>SecuBox is a comprehensive security and network management suite for OpenWrt. The repository contains 13 LuCI application packages that provide dashboards for security monitoring, network intelligence, access control, bandwidth management, and system administration.</p>"},{"location":"claude/#build-commands","title":"Build Commands","text":""},{"location":"claude/#openwrt-sdk-build","title":"OpenWrt SDK Build","text":"<pre><code># Build a single package\nmake package/luci-app-<module-name>/compile V=s\n\n# Clean build for a package\nmake package/luci-app-<module-name>/clean\nmake package/luci-app-<module-name>/compile V=s\n\n# Install package to staging directory\nmake package/luci-app-<module-name>/install\n</code></pre>"},{"location":"claude/#testing-packages","title":"Testing Packages","text":"<pre><code># Transfer to router\nscp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/\n\n# Install on router\nssh root@192.168.1.1\nopkg install /tmp/luci-app-*.ipk\n/etc/init.d/rpcd restart\n/etc/init.d/uhttpd restart\n</code></pre>"},{"location":"claude/#validation","title":"Validation","text":"<pre><code># Fix file permissions FIRST (CRITICAL)\n./secubox-tools/fix-permissions.sh --local\n\n# Run comprehensive module validation (RECOMMENDED - 7 checks)\n./secubox-tools/validate-modules.sh\n# Checks:\n# 1. RPCD script names vs ubus objects\n# 2. Menu paths vs view file locations\n# 3. View files have menu entries\n# 4. RPCD script permissions (755)\n# 5. JSON syntax validation\n# 6. ubus object naming convention\n# 7. htdocs file permissions (644 for CSS/JS) \u2190 NEW\n\n# Validate shell scripts (RPCD backends)\nshellcheck luci-app-*/root/usr/libexec/rpcd/*\n\n# Validate JSON files\nfind . -name \"*.json\" -exec jsonlint {} \\;\n\n# Run automated repair tool\n./secubox-tools/secubox-repair.sh\n\n# Fix permissions on deployed router\n./secubox-tools/fix-permissions.sh --remote\n\n# Run diagnostics\n./secubox-tools/secubox-debug.sh luci-app-<module-name>\n</code></pre>"},{"location":"claude/#local-build-replicates-github-actions","title":"Local Build (Replicates GitHub Actions)","text":"<p>The <code>local-build.sh</code> script allows you to build and test packages locally, replicating the GitHub Actions workflows:</p> <pre><code># Validate all packages (syntax, JSON, shell scripts)\n./secubox-tools/local-build.sh validate\n\n# Build all packages for x86_64\n./secubox-tools/local-build.sh build\n\n# Build single package\n./secubox-tools/local-build.sh build luci-app-system-hub\n\n# Build for specific architecture\n./secubox-tools/local-build.sh build --arch aarch64-cortex-a72\n\n# Full validation + build\n./secubox-tools/local-build.sh full\n\n# Clean build artifacts\n./secubox-tools/local-build.sh clean\n</code></pre> <p>Supported architectures: - <code>x86-64</code> - PC, VMs (default) - <code>aarch64-cortex-a53</code> - ARM Cortex-A53 (ESPRESSObin) - <code>aarch64-cortex-a72</code> - ARM Cortex-A72 (MOCHAbin, RPi4) - <code>aarch64-generic</code> - Generic ARM64 - <code>mips-24kc</code> - MIPS 24Kc (TP-Link) - <code>mipsel-24kc</code> - MIPS LE (Xiaomi, GL.iNet)</p> <p>The script automatically: - Downloads and caches the OpenWrt SDK - Configures feeds (packages, luci) with correct branch for version - Copies your packages to the SDK - Builds packages (.apk for 25.12+, .ipk for older versions) - Collects artifacts in <code>build/<arch>/</code></p> <p>Package Format Support: - OpenWrt 25.12+ and SNAPSHOT: <code>.apk</code> format (new Alpine-based package manager) - OpenWrt 24.10 and earlier: <code>.ipk</code> format (opkg package manager)</p> <p>Environment variables: - <code>OPENWRT_VERSION</code> - OpenWrt version (default: 24.10.5, also supports: 25.12.0-rc1, 23.05.5, SNAPSHOT) - <code>SDK_DIR</code> - SDK directory (default: ./sdk) - <code>BUILD_DIR</code> - Build output directory (default: ./build) - <code>CACHE_DIR</code> - Download cache directory (default: ./cache)</p>"},{"location":"claude/#architecture","title":"Architecture","text":""},{"location":"claude/#luci-package-structure","title":"LuCI Package Structure","text":"<p>All SecuBox modules follow a standard LuCI application structure:</p> <pre><code>luci-app-<module-name>/\n\u251c\u2500\u2500 Makefile # OpenWrt package definition\n\u251c\u2500\u2500 README.md # Module documentation\n\u251c\u2500\u2500 htdocs/luci-static/resources/\n\u2502 \u251c\u2500\u2500 view/<module-name>/ # JavaScript UI views\n\u2502 \u2502 \u251c\u2500\u2500 overview.js # Main dashboard view\n\u2502 \u2502 \u2514\u2500\u2500 *.js # Additional views\n\u2502 \u2514\u2500\u2500 <module-name>/\n\u2502 \u251c\u2500\u2500 api.js # RPC API client module\n\u2502 \u2514\u2500\u2500 dashboard.css # Module-specific styles\n\u2514\u2500\u2500 root/\n \u251c\u2500\u2500 etc/config/<module-name> # UCI configuration (optional)\n \u2514\u2500\u2500 usr/\n \u251c\u2500\u2500 libexec/rpcd/\n \u2502 \u2514\u2500\u2500 luci.<module-name> # RPCD backend script (MUST use luci. prefix!)\n \u2514\u2500\u2500 share/\n \u251c\u2500\u2500 luci/menu.d/ # Menu JSON definition\n \u2502 \u2514\u2500\u2500 luci-app-<module-name>.json\n \u2514\u2500\u2500 rpcd/acl.d/ # ACL permissions JSON\n \u2514\u2500\u2500 luci-app-<module-name>.json\n</code></pre>"},{"location":"claude/#frontend-backend-communication","title":"Frontend-Backend Communication","text":"<ol> <li>Frontend (JavaScript): Located in <code>htdocs/luci-static/resources/</code></li> <li>Views use LuCI's <code>form</code> and <code>view</code> classes</li> <li>API calls via <code>api.js</code> module using <code>L.resolveDefault()</code></li> <li> <p>UI components from <code>ui.js</code> (Dropdown, Checkbox, Combobox, etc.)</p> </li> <li> <p>Backend (RPCD): Located in <code>root/usr/libexec/rpcd/</code></p> </li> <li>Shell scripts that implement RPC methods</li> <li>Must output JSON to stdout</li> <li> <p>Methods are called via ubus: <code>ubus call <module> <method></code></p> </li> <li> <p>Menu Definition: <code>root/usr/share/luci/menu.d/luci-app-<module>.json</code></p> </li> <li>Defines menu structure and navigation</li> <li> <p>Specifies view paths and dependencies</p> </li> <li> <p>ACL Definition: <code>root/usr/share/rpcd/acl.d/luci-app-<module>.json</code></p> </li> <li>Defines access control for ubus methods</li> <li>Maps read/write permissions to user groups</li> </ol>"},{"location":"claude/#critical-naming-conventions","title":"Critical Naming Conventions","text":"<p>IMPORTANT: The following naming rules are MANDATORY for modules to work correctly:</p>"},{"location":"claude/#1-rpcd-script-must-match-ubus-object-name","title":"1. RPCD Script Must Match ubus Object Name","text":"<p>The RPCD script filename MUST exactly match the ubus object name used in JavaScript:</p> <pre><code>// In JavaScript (htdocs/luci-static/resources/view/*/):\nvar callStatus = rpc.declare({\n object: 'luci.cdn-cache', // \u2190 This object name\n method: 'status'\n});\n</code></pre> <pre><code># RPCD script filename MUST match:\nroot/usr/libexec/rpcd/luci.cdn-cache # \u2190 Must be exactly 'luci.cdn-cache'\n</code></pre> <p>Common Error: If the names don't match, you'll get: - <code>RPC call to luci.cdn-cache/status failed with error -32000: Object not found</code> - <code>Command failed: Method not found</code></p> <p>Solution: All RPCD scripts MUST use the <code>luci.</code> prefix: - \u2705 Correct: <code>luci.cdn-cache</code>, <code>luci.system-hub</code>, <code>luci.wireguard-dashboard</code> - \u274c Wrong: <code>cdn-cache</code>, <code>system-hub</code>, <code>wireguard-dashboard</code></p>"},{"location":"claude/#2-menu-paths-must-match-view-file-locations","title":"2. Menu Paths Must Match View File Locations","text":"<p>Menu JSON path entries MUST correspond to actual view files:</p> <pre><code>// In menu.d/luci-app-netifyd-dashboard.json:\n{\n \"action\": {\n \"type\": \"view\",\n \"path\": \"netifyd-dashboard/overview\" // \u2190 Must match file location\n }\n}\n</code></pre> <pre><code># View file MUST exist at:\nhtdocs/luci-static/resources/view/netifyd-dashboard/overview.js\n# \u2191 Same path as menu \u2191\n</code></pre> <p>Common Error: If paths don't match: - <code>HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'</code></p> <p>Solution: Ensure menu paths match directory structure: - \u2705 Correct: Menu path <code>netifyd-dashboard/overview</code> \u2192 file <code>view/netifyd-dashboard/overview.js</code> - \u274c Wrong: Menu path <code>netifyd/overview</code> \u2192 file <code>view/netifyd-dashboard/overview.js</code></p>"},{"location":"claude/#3-ubus-object-naming-convention","title":"3. ubus Object Naming Convention","text":"<p>All ubus objects MUST start with <code>luci.</code> prefix:</p> <pre><code>// \u2705 Correct:\nobject: 'luci.cdn-cache'\nobject: 'luci.system-hub'\nobject: 'luci.wireguard-dashboard'\n\n// \u274c Wrong:\nobject: 'cdn-cache'\nobject: 'systemhub'\n</code></pre>"},{"location":"claude/#4-validation-before-deployment","title":"4. Validation Before Deployment","text":"<p>ALWAYS run validation before deploying:</p> <pre><code>./secubox-tools/validate-modules.sh\n</code></pre> <p>This script checks: - RPCD script names match ubus objects - Menu paths match view file locations - View files have corresponding menu entries - RPCD scripts are executable - JSON files are valid syntax - ubus objects follow naming convention</p>"},{"location":"claude/#makefile-structure","title":"Makefile Structure","text":"<p>Each package Makefile must define: - <code>PKG_NAME</code>: Package name (must match directory) - <code>PKG_VERSION</code>: Version number - <code>PKG_RELEASE</code>: Package release number - <code>LUCI_TITLE</code>: Display title in LuCI - <code>LUCI_DEPENDS</code>: Package dependencies (e.g., <code>+luci-base +rpcd</code>) - <code>LUCI_DESCRIPTION</code>: Brief description - <code>PKG_MAINTAINER</code>: Maintainer name and email - <code>PKG_LICENSE</code>: License (typically Apache-2.0)</p> <p>The Makefile includes <code>luci.mk</code> from the LuCI build system which handles installation.</p>"},{"location":"claude/#common-development-patterns","title":"Common Development Patterns","text":""},{"location":"claude/#creating-a-new-module","title":"Creating a New Module","text":"<ol> <li>Copy template: <code>cp -r templates/luci-app-template luci-app-newmodule</code></li> <li>Update Makefile with new PKG_NAME, LUCI_TITLE, etc.</li> <li>Create directory structure under <code>htdocs/</code> and <code>root/</code></li> <li>Implement RPCD backend in shell</li> <li>Create JavaScript views</li> <li>Define menu and ACL JSON files</li> </ol>"},{"location":"claude/#rpcd-backend-pattern","title":"RPCD Backend Pattern","text":"<p>RPCD backends are shell scripts that: - Parse <code>$1</code> for the method name - Output valid JSON using <code>printf</code> or <code>echo</code> - Use <code>case</code> statements for method routing - Source UCI config if needed: <code>. /lib/functions.sh</code></p> <p>Example: <pre><code>#!/bin/sh\ncase \"$1\" in\n list)\n echo '{ \"status\": {}, \"stats\": {} }'\n ;;\n call)\n case \"$2\" in\n status)\n # Output JSON\n printf '{\"running\": true, \"version\": \"1.0.0\"}\\n'\n ;;\n esac\n ;;\nesac\n</code></pre></p>"},{"location":"claude/#javascript-view-pattern","title":"JavaScript View Pattern","text":"<p>Views extend <code>L.view</code> and implement <code>load()</code> and <code>render()</code>:</p> <pre><code>'use strict';\n'require view';\n'require form';\n'require <module>/api as API';\n\nreturn L.view.extend({\n load: function() {\n return Promise.all([\n API.getStatus(),\n API.getStats()\n ]);\n },\n\n render: function(data) {\n var m, s, o;\n m = new form.Map('config', _('Title'));\n s = m.section(form.TypedSection, 'section');\n // Add form fields...\n return m.render();\n }\n});\n</code></pre>"},{"location":"claude/#module-categories","title":"Module Categories","text":"<ol> <li>Core Control (2 modules)</li> <li>luci-app-secubox: Central hub</li> <li> <p>luci-app-system-hub: System control center</p> </li> <li> <p>Security & Monitoring (2 modules)</p> </li> <li>luci-app-crowdsec-dashboard: CrowdSec security</li> <li> <p>luci-app-netdata-dashboard: System monitoring</p> </li> <li> <p>Network Intelligence (2 modules)</p> </li> <li>luci-app-netifyd-dashboard: Deep packet inspection</li> <li> <p>luci-app-network-modes: Network mode configuration</p> </li> <li> <p>VPN & Access Control (3 modules)</p> </li> <li>luci-app-wireguard-dashboard: WireGuard VPN</li> <li>luci-app-client-guardian: NAC & captive portal</li> <li> <p>luci-app-auth-guardian: Authentication system</p> </li> <li> <p>Bandwidth & Traffic (2 modules)</p> </li> <li>luci-app-bandwidth-manager: QoS & quotas</li> <li> <p>luci-app-media-flow: Media traffic detection</p> </li> <li> <p>Performance & Services (2 modules)</p> </li> <li>luci-app-cdn-cache: CDN proxy cache</li> <li>luci-app-vhost-manager: Virtual host manager</li> </ol>"},{"location":"claude/#cicd-integration","title":"CI/CD Integration","text":""},{"location":"claude/#github-actions-workflows","title":"GitHub Actions Workflows","text":"<ol> <li>build-openwrt-packages.yml: Compiles packages for all architectures</li> <li>Triggers on push, PR, and tags</li> <li>Matrix build for 13 architectures</li> <li> <p>Uploads artifacts per architecture</p> </li> <li> <p>build-secubox-images.yml: Builds custom OpenWrt images</p> </li> <li> <p>Creates complete firmware images with SecuBox pre-installed</p> </li> <li> <p>test-validate.yml: Validation and testing</p> </li> <li>Validates Makefile structure</li> <li>Checks JSON syntax</li> <li>Runs shellcheck on scripts</li> <li>Verifies file permissions</li> </ol>"},{"location":"claude/#supported-architectures","title":"Supported Architectures","text":"<p>ARM64: aarch64-cortex-a53, aarch64-cortex-a72, aarch64-generic, mediatek-filogic, rockchip-armv8, bcm27xx-bcm2711</p> <p>ARM32: arm-cortex-a7-neon, arm-cortex-a9-neon, qualcomm-ipq40xx, qualcomm-ipq806x</p> <p>MIPS: mips-24kc, mipsel-24kc, mipsel-74kc</p> <p>x86: x86-64, x86-generic</p>"},{"location":"claude/#key-files-and-directories","title":"Key Files and Directories","text":"<ul> <li><code>makefiles/</code>: Reference Makefiles for modules (backup/templates)</li> <li><code>secubox-tools/</code>: Repair and debugging utilities</li> <li><code>secubox-repair.sh</code>: Auto-fixes Makefile and RPCD issues</li> <li><code>secubox-debug.sh</code>: Validates package structure</li> <li><code>templates/</code>: Package templates for creating new modules</li> <li><code>.github/workflows/</code>: CI/CD automation scripts</li> </ul>"},{"location":"claude/#common-issues-and-solutions","title":"Common Issues and Solutions","text":""},{"location":"claude/#rpc-errors-object-not-found-or-method-not-found","title":"RPC Errors: \"Object not found\" or \"Method not found\"","text":"<p>Error: <code>RPC call to luci.cdn-cache/status failed with error -32000: Object not found</code></p> <p>Cause: RPCD script name doesn't match ubus object name in JavaScript</p> <p>Solution: 1. Check JavaScript files for ubus object name: <pre><code>grep -r \"object:\" luci-app-*/htdocs --include=\"*.js\"\n</code></pre> 2. Rename RPCD script to match exactly (including <code>luci.</code> prefix): <pre><code>mv root/usr/libexec/rpcd/cdn-cache root/usr/libexec/rpcd/luci.cdn-cache\n</code></pre> 3. Restart RPCD on router: <pre><code>/etc/init.d/rpcd restart\n</code></pre></p>"},{"location":"claude/#http-404-errors-view-files-not-found","title":"HTTP 404 Errors: View Files Not Found","text":"<p>Error: <code>HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'</code></p> <p>Cause: Menu path doesn't match actual view file location</p> <p>Solution: 1. Check menu JSON for path: <pre><code>grep '\"path\":' root/usr/share/luci/menu.d/*.json\n</code></pre> 2. Verify view file exists at matching location: <pre><code>ls htdocs/luci-static/resources/view/\n</code></pre> 3. Update menu path to match file location OR move file to match menu path</p>"},{"location":"claude/#rpcd-not-responding","title":"RPCD Not Responding","text":"<p>After installing/updating a package: <pre><code>/etc/init.d/rpcd restart\n/etc/init.d/uhttpd restart\n</code></pre></p>"},{"location":"claude/#menu-not-appearing","title":"Menu Not Appearing","text":"<p>Check that: 1. Menu JSON is valid: <code>jsonlint root/usr/share/luci/menu.d/*.json</code> 2. ACL grants access: Check <code>root/usr/share/rpcd/acl.d/*.json</code> 3. Dependencies are installed: Check Makefile <code>LUCI_DEPENDS</code> 4. Menu path matches view file location (see above)</p>"},{"location":"claude/#build-failures","title":"Build Failures","text":"<p>Common causes: 1. Missing fields in Makefile (PKG_NAME, LUCI_TITLE, etc.) 2. Invalid JSON syntax in menu.d or acl.d 3. RPCD script not executable (chmod +x needed) 4. Wrong include path (should be <code>include ../../luci.mk</code>) 5. RPCD script name doesn't match ubus object (must use <code>luci.</code> prefix)</p> <p>Use repair tool: <code>./secubox-tools/secubox-repair.sh</code></p>"},{"location":"claude/#quick-diagnosis","title":"Quick Diagnosis","text":"<p>Run the validation script to check all naming conventions: <pre><code>./secubox-tools/validate-modules.sh\n</code></pre></p>"},{"location":"claude/#development-workflow","title":"Development Workflow","text":"<ol> <li>Make changes to module files</li> <li>Run validation checks (CRITICAL): <pre><code>./secubox-tools/validate-modules.sh\n# Or use the local build tool:\n./secubox-tools/local-build.sh validate\n</code></pre></li> <li>Test JSON syntax: <code>jsonlint <file>.json</code></li> <li>Test shell scripts: <code>shellcheck <script></code></li> <li>Build and test package locally (recommended): <pre><code># Build single package\n./secubox-tools/local-build.sh build luci-app-<name>\n\n# Or build with manual SDK:\nmake package/luci-app-<name>/compile V=s\n</code></pre></li> <li>Install on test router and verify functionality</li> <li>Run repair tool if needed: <code>./secubox-tools/secubox-repair.sh</code></li> <li>Commit changes and push (triggers CI validation)</li> <li>Create tag for release: <code>git tag -a v1.0.0 -m \"Release 1.0.0\"</code></li> </ol>"},{"location":"claude/#important-notes","title":"Important Notes","text":"<ul> <li>CRITICAL: RPCD script names MUST match ubus object names (use <code>luci.</code> prefix)</li> <li>CRITICAL: Menu paths MUST match view file directory structure</li> <li>CRITICAL: Always run <code>./secubox-tools/validate-modules.sh</code> before committing</li> <li>All modules use Apache-2.0 license</li> <li>RPCD backends must be executable (chmod +x)</li> <li>JavaScript files use strict mode: <code>'use strict';</code></li> <li>Menu entries require proper dependency chain</li> <li>ACL must grant both ubus call and luci-cgi access</li> <li>UCI config files are optional (many modules don't need them)</li> <li>All packages build as architecture <code>all</code> (no compiled code)</li> </ul>"},{"location":"code-templates/","title":"SecuBox Module Code Templates","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active Purpose: Ready-to-use code templates extracted from working SecuBox modules</p>"},{"location":"code-templates/#see-also","title":"See Also","text":"<ul> <li>Implementation Workflow: MODULE-IMPLEMENTATION-GUIDE.md</li> <li>Quick Commands: QUICK-START.md</li> <li>Automation Guardrails: CODEX.md</li> <li>Module Prompts: FEATURE-REGENERATION-PROMPTS.md</li> </ul>"},{"location":"code-templates/#table-of-contents","title":"Table of Contents","text":"<ol> <li>File Structure Template</li> <li>API Module Template</li> <li>JavaScript View Template</li> <li>RPCD Backend Template</li> <li>Menu JSON Template</li> <li>ACL JSON Template</li> <li>CSS Styling Template</li> <li>Complete Implementation Example</li> </ol>"},{"location":"code-templates/#file-structure-template","title":"File Structure Template","text":"<p>Every SecuBox module follows this exact structure:</p> <pre><code>luci-app-<module-name>/\n\u251c\u2500\u2500 Makefile # OpenWrt package definition\n\u251c\u2500\u2500 README.md # Module documentation\n\u251c\u2500\u2500 htdocs/luci-static/resources/\n\u2502 \u251c\u2500\u2500 <module-name>/\n\u2502 \u2502 \u251c\u2500\u2500 api.js # RPC API client (REQUIRED)\n\u2502 \u2502 \u251c\u2500\u2500 theme.js # Theme helper (optional)\n\u2502 \u2502 \u2514\u2500\u2500 dashboard.css # Module-specific styles\n\u2502 \u2514\u2500\u2500 view/<module-name>/\n\u2502 \u251c\u2500\u2500 overview.js # Main dashboard view\n\u2502 \u251c\u2500\u2500 settings.js # Settings view (if needed)\n\u2502 \u2514\u2500\u2500 *.js # Additional views\n\u2514\u2500\u2500 root/\n \u251c\u2500\u2500 etc/config/<module-name> # UCI config (optional)\n \u2514\u2500\u2500 usr/\n \u251c\u2500\u2500 libexec/rpcd/\n \u2502 \u2514\u2500\u2500 luci.<module-name> # RPCD backend (REQUIRED, must be executable)\n \u2514\u2500\u2500 share/\n \u251c\u2500\u2500 luci/menu.d/\n \u2502 \u2514\u2500\u2500 luci-app-<module-name>.json # Menu definition\n \u2514\u2500\u2500 rpcd/acl.d/\n \u2514\u2500\u2500 luci-app-<module-name>.json # ACL permissions\n</code></pre> <p>Critical Rules: 1. RPCD script MUST be named <code>luci.<module-name></code> (with <code>luci.</code> prefix) 2. RPCD script MUST be executable (<code>chmod +x</code>) 3. Menu paths MUST match view file locations 4. CSS/JS files should be 644 permissions 5. All ubus objects MUST use <code>luci.</code> prefix</p>"},{"location":"code-templates/#api-module-template","title":"API Module Template","text":"<p>File: <code>htdocs/luci-static/resources/<module-name>/api.js</code></p> <pre><code>'use strict';\n'require baseclass';\n'require rpc';\n\n/**\n * [Module Name] API\n * Package: luci-app-<module-name>\n * RPCD object: luci.<module-name>\n * Version: 1.0.0\n */\n\n// Debug log to verify correct version is loaded\nconsole.log('\ud83d\udd27 [Module Name] API v1.0.0 loaded at', new Date().toISOString());\n\n// ============================================================================\n// RPC Method Declarations\n// ============================================================================\n\n// Simple method (no parameters)\nvar callStatus = rpc.declare({\n object: 'luci.<module-name>', // MUST match RPCD script name\n method: 'status',\n expect: {}\n});\n\n// Method with return structure\nvar callGetData = rpc.declare({\n object: 'luci.<module-name>',\n method: 'get_data',\n expect: { data: [] } // Expected return structure\n});\n\n// Method with parameters\nvar callPerformAction = rpc.declare({\n object: 'luci.<module-name>',\n method: 'perform_action',\n params: ['action_type', 'target'], // Parameter names\n expect: { success: false }\n});\n\n// Method with multiple parameters\nvar callUpdateConfig = rpc.declare({\n object: 'luci.<module-name>',\n method: 'update_config',\n params: ['key', 'value', 'persist'],\n expect: {}\n});\n\n// ============================================================================\n// Helper Functions (Optional)\n// ============================================================================\n\n/**\n * Format bytes to human-readable string\n */\nfunction formatBytes(bytes) {\n if (bytes === 0) return '0 B';\n var k = 1024;\n var sizes = ['B', 'KB', 'MB', 'GB', 'TB'];\n var i = Math.floor(Math.log(bytes) / Math.log(k));\n return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];\n}\n\n/**\n * Format timestamp to \"X ago\" string\n */\nfunction formatTimeAgo(timestamp) {\n if (!timestamp) return 'Never';\n var now = Math.floor(Date.now() / 1000);\n var diff = now - timestamp;\n if (diff < 60) return diff + 's ago';\n if (diff < 3600) return Math.floor(diff / 60) + 'm ago';\n if (diff < 86400) return Math.floor(diff / 3600) + 'h ago';\n return Math.floor(diff / 86400) + 'd ago';\n}\n\n/**\n * Format uptime seconds to \"Xd Xh Xm\" string\n */\nfunction formatUptime(seconds) {\n var days = Math.floor(seconds / 86400);\n var hours = Math.floor((seconds % 86400) / 3600);\n var mins = Math.floor((seconds % 3600) / 60);\n return days + 'd ' + hours + 'h ' + mins + 'm';\n}\n\n// ============================================================================\n// API Export\n// ============================================================================\n\nreturn baseclass.extend({\n // RPC methods - exposed via ubus\n getStatus: callStatus,\n getData: callGetData,\n performAction: callPerformAction,\n updateConfig: callUpdateConfig,\n\n // Helper functions\n formatBytes: formatBytes,\n formatTimeAgo: formatTimeAgo,\n formatUptime: formatUptime,\n\n // Aggregate function for overview page (combines multiple calls)\n getAllData: function() {\n return Promise.all([\n callStatus(),\n callGetData()\n ]).then(function(results) {\n return {\n status: results[0] || {},\n data: results[1] || { data: [] }\n };\n });\n }\n});\n</code></pre> <p>Key Points: - Always use <code>'use strict';</code> - Require <code>baseclass</code> and <code>rpc</code> - Use <code>rpc.declare()</code> for each RPCD method - Export from <code>baseclass.extend()</code> - Helper functions can be included in the API module - Aggregate functions are useful for views that need multiple data sources</p>"},{"location":"code-templates/#javascript-view-template","title":"JavaScript View Template","text":"<p>File: <code>htdocs/luci-static/resources/view/<module-name>/overview.js</code></p> <pre><code>'use strict';\n'require view';\n'require ui';\n'require dom';\n'require poll';\n'require <module-name>/api as API';\n\n/**\n * [Module Name] - Overview Dashboard\n * Main view for luci-app-<module-name>\n */\n\nreturn view.extend({\n // ========================================================================\n // Data Properties\n // ========================================================================\n\n statusData: null,\n componentData: null,\n\n // ========================================================================\n // Load Data\n // ========================================================================\n\n /**\n * Called when view is loaded\n * Return a Promise (can use Promise.all for parallel loading)\n */\n load: function() {\n return Promise.all([\n API.getStatus(),\n API.getData()\n ]);\n },\n\n // ========================================================================\n // Render View\n // ========================================================================\n\n /**\n * Called after load() completes\n * @param {Array} data - Results from load() Promise.all\n */\n render: function(data) {\n var self = this;\n this.statusData = data[0] || {};\n this.componentData = data[1] || { data: [] };\n\n // Main container\n var container = E('div', { 'class': 'module-dashboard' }, [\n // Load CSS\n E('link', { 'rel': 'stylesheet', 'href': L.resource('<module-name>/dashboard.css') }),\n\n // Page Header\n this.renderHeader(),\n\n // Stats Overview Grid\n this.renderStatsOverview(),\n\n // Content Cards\n this.renderContent()\n ]);\n\n // Setup auto-refresh polling (30 seconds)\n poll.add(L.bind(function() {\n return Promise.all([\n API.getStatus(),\n API.getData()\n ]).then(L.bind(function(refreshData) {\n this.statusData = refreshData[0] || {};\n this.componentData = refreshData[1] || { data: [] };\n this.updateDashboard();\n }, this));\n }, this), 30);\n\n return container;\n },\n\n // ========================================================================\n // Render Components\n // ========================================================================\n\n /**\n * Render page header with title and stats badges\n */\n renderHeader: function() {\n return E('div', { 'class': 'sh-page-header' }, [\n E('div', {}, [\n E('h2', { 'class': 'sh-page-title' }, [\n E('span', { 'class': 'sh-page-title-icon' }, '\ud83d\ude80'),\n 'Module Title'\n ]),\n E('p', { 'class': 'sh-page-subtitle' }, 'Module description and purpose')\n ]),\n E('div', { 'class': 'sh-stats-grid' }, [\n this.renderStatBadge('Active Items', this.statusData.active || 0),\n this.renderStatBadge('Total Items', this.statusData.total || 0),\n this.renderStatBadge('Status', this.statusData.status || 'Unknown'),\n this.renderStatBadge('Version', this.statusData.version || '1.0.0')\n ])\n ]);\n },\n\n /**\n * Render a single stat badge\n */\n renderStatBadge: function(label, value) {\n return E('div', { 'class': 'sh-stat-badge' }, [\n E('div', { 'class': 'sh-stat-value' }, String(value)),\n E('div', { 'class': 'sh-stat-label' }, label)\n ]);\n },\n\n /**\n * Render stats overview grid\n */\n renderStatsOverview: function() {\n return E('div', { 'class': 'stats-grid' }, [\n this.renderMetricCard('CPU', this.statusData.cpu),\n this.renderMetricCard('Memory', this.statusData.memory),\n this.renderMetricCard('Disk', this.statusData.disk)\n ]);\n },\n\n /**\n * Render a metric card with progress bar\n */\n renderMetricCard: function(title, data) {\n if (!data) return E('div');\n\n var usage = data.usage || 0;\n var status = usage >= 90 ? 'critical' : (usage >= 75 ? 'warning' : 'ok');\n var color = usage >= 90 ? '#ef4444' : (usage >= 75 ? '#f59e0b' : '#22c55e');\n\n return E('div', { 'class': 'sh-metric-card sh-metric-' + status }, [\n E('div', { 'class': 'sh-metric-header' }, [\n E('span', { 'class': 'sh-metric-icon' }, this.getMetricIcon(title)),\n E('span', { 'class': 'sh-metric-title' }, title)\n ]),\n E('div', { 'class': 'sh-metric-value' }, usage + '%'),\n E('div', { 'class': 'sh-metric-progress' }, [\n E('div', {\n 'class': 'sh-metric-progress-bar',\n 'style': 'width: ' + usage + '%; background: ' + color\n })\n ]),\n E('div', { 'class': 'sh-metric-details' }, data.details || 'N/A')\n ]);\n },\n\n /**\n * Get icon for metric type\n */\n getMetricIcon: function(type) {\n switch(type) {\n case 'CPU': return '\ud83d\udd25';\n case 'Memory': return '\ud83d\udcbe';\n case 'Disk': return '\ud83d\udcbf';\n default: return '\ud83d\udcca';\n }\n },\n\n /**\n * Render main content\n */\n renderContent: function() {\n return E('div', { 'class': 'content-grid' }, [\n this.renderCard('Active Components', this.renderComponentsList()),\n this.renderCard('Quick Actions', this.renderQuickActions()),\n this.renderCard('Recent Activity', this.renderActivityLog())\n ]);\n },\n\n /**\n * Render a card container\n */\n renderCard: function(title, content) {\n return E('div', { 'class': 'sh-card' }, [\n E('div', { 'class': 'sh-card-header' }, [\n E('h3', { 'class': 'sh-card-title' }, title)\n ]),\n E('div', { 'class': 'sh-card-body' }, content)\n ]);\n },\n\n /**\n * Render components list\n */\n renderComponentsList: function() {\n var items = this.componentData.data || [];\n\n if (items.length === 0) {\n return E('div', { 'class': 'sh-empty-state' }, [\n E('div', { 'class': 'sh-empty-icon' }, '\ud83d\udced'),\n E('div', { 'class': 'sh-empty-text' }, 'No components found')\n ]);\n }\n\n return E('div', { 'class': 'component-list' },\n items.map(L.bind(function(item) {\n return this.renderComponentItem(item);\n }, this))\n );\n },\n\n /**\n * Render a single component item\n */\n renderComponentItem: function(item) {\n var statusClass = item.status === 'active' ? 'sh-card-success' : 'sh-card-warning';\n\n return E('div', { 'class': 'component-item ' + statusClass }, [\n E('div', { 'class': 'component-name' }, item.name || 'Unknown'),\n E('div', { 'class': 'component-status' }, item.status || 'unknown'),\n E('div', { 'class': 'component-actions' }, [\n E('button', {\n 'class': 'sh-btn sh-btn-primary sh-btn-sm',\n 'click': L.bind(this.handleAction, this, item.id, 'view')\n }, 'View'),\n E('button', {\n 'class': 'sh-btn sh-btn-secondary sh-btn-sm',\n 'click': L.bind(this.handleAction, this, item.id, 'configure')\n }, 'Configure')\n ])\n ]);\n },\n\n /**\n * Render quick actions\n */\n renderQuickActions: function() {\n return E('div', { 'class': 'quick-actions' }, [\n E('button', {\n 'class': 'sh-btn sh-btn-primary',\n 'click': L.bind(this.handleRefresh, this)\n }, '\ud83d\udd04 Refresh'),\n E('button', {\n 'class': 'sh-btn sh-btn-success',\n 'click': L.bind(this.handleAction, this, null, 'start_all')\n }, '\u25b6\ufe0f Start All'),\n E('button', {\n 'class': 'sh-btn sh-btn-danger',\n 'click': L.bind(this.handleAction, this, null, 'stop_all')\n }, '\u23f9\ufe0f Stop All')\n ]);\n },\n\n /**\n * Render activity log\n */\n renderActivityLog: function() {\n var activities = this.statusData.recent_activities || [];\n\n if (activities.length === 0) {\n return E('div', { 'class': 'sh-empty-text' }, 'No recent activity');\n }\n\n return E('div', { 'class': 'activity-log' },\n activities.map(function(activity) {\n return E('div', { 'class': 'activity-item' }, [\n E('span', { 'class': 'activity-time' }, activity.time || ''),\n E('span', { 'class': 'activity-text' }, activity.message || '')\n ]);\n })\n );\n },\n\n // ========================================================================\n // Event Handlers\n // ========================================================================\n\n /**\n * Handle generic action\n */\n handleAction: function(id, action, ev) {\n var self = this;\n\n ui.showModal(_('Performing Action'), [\n E('p', {}, _('Please wait...'))\n ]);\n\n API.performAction(action, id || '').then(function(result) {\n ui.hideModal();\n\n if (result.success) {\n ui.addNotification(null, E('p', _('Action completed successfully')), 'success');\n self.handleRefresh();\n } else {\n ui.addNotification(null, E('p', _('Action failed: %s').format(result.message || 'Unknown error')), 'error');\n }\n }).catch(function(error) {\n ui.hideModal();\n ui.addNotification(null, E('p', _('Error: %s').format(error.message || 'Unknown error')), 'error');\n });\n },\n\n /**\n * Handle refresh\n */\n handleRefresh: function() {\n var self = this;\n\n return Promise.all([\n API.getStatus(),\n API.getData()\n ]).then(function(data) {\n self.statusData = data[0] || {};\n self.componentData = data[1] || { data: [] };\n self.updateDashboard();\n ui.addNotification(null, E('p', _('Dashboard refreshed')), 'info');\n });\n },\n\n /**\n * Update dashboard without full re-render\n */\n updateDashboard: function() {\n // Update specific DOM elements instead of full re-render\n var statsGrid = document.querySelector('.sh-stats-grid');\n if (statsGrid) {\n dom.content(statsGrid, [\n this.renderStatBadge('Active Items', this.statusData.active || 0),\n this.renderStatBadge('Total Items', this.statusData.total || 0),\n this.renderStatBadge('Status', this.statusData.status || 'Unknown'),\n this.renderStatBadge('Version', this.statusData.version || '1.0.0')\n ]);\n }\n\n // Update components list\n var componentsList = document.querySelector('.component-list');\n if (componentsList) {\n var items = this.componentData.data || [];\n dom.content(componentsList,\n items.map(L.bind(function(item) {\n return this.renderComponentItem(item);\n }, this))\n );\n }\n },\n\n // ========================================================================\n // Required LuCI Methods (can be null if not used)\n // ========================================================================\n\n handleSaveApply: null,\n handleSave: null,\n handleReset: null\n});\n</code></pre> <p>Key Points: - Extend <code>view</code> with <code>load()</code> and <code>render()</code> methods - Use <code>E()</code> helper to build DOM elements - Use <code>L.bind()</code> for event handlers to preserve <code>this</code> context - Use <code>poll.add()</code> for auto-refresh functionality - Use <code>dom.content()</code> for efficient partial updates - Use <code>ui.showModal()</code>, <code>ui.hideModal()</code>, <code>ui.addNotification()</code> for user feedback - Always handle errors in Promise chains</p>"},{"location":"code-templates/#rpcd-backend-template","title":"RPCD Backend Template","text":"<p>File: <code>root/usr/libexec/rpcd/luci.<module-name></code></p> <pre><code>#!/bin/sh\n# [Module Name] RPCD Backend\n# Package: luci-app-<module-name>\n# Version: 1.0.0\n\n# Source required libraries\n. /lib/functions.sh\n. /usr/share/libubox/jshn.sh\n\n# ============================================================================\n# RPC Methods\n# ============================================================================\n\n# Get status information\nstatus() {\n json_init\n\n # Example: Get system info\n local hostname=$(cat /proc/sys/kernel/hostname 2>/dev/null || echo \"unknown\")\n local uptime=$(awk '{print int($1)}' /proc/uptime 2>/dev/null || echo 0)\n\n json_add_string \"hostname\" \"$hostname\"\n json_add_int \"uptime\" \"$uptime\"\n json_add_string \"version\" \"1.0.0\"\n json_add_string \"status\" \"running\"\n\n # Add nested object\n json_add_object \"cpu\"\n local cpu_load=$(awk '{print $1}' /proc/loadavg 2>/dev/null || echo \"0\")\n json_add_string \"load\" \"$cpu_load\"\n json_add_int \"usage\" \"45\"\n json_close_object\n\n # Add timestamp\n json_add_string \"timestamp\" \"$(date '+%Y-%m-%d %H:%M:%S')\"\n\n json_dump\n}\n\n# Get data with array\nget_data() {\n json_init\n json_add_array \"data\"\n\n # Example: List files\n for file in /etc/config/*; do\n [ -f \"$file\" ] || continue\n local name=$(basename \"$file\")\n\n json_add_object \"\"\n json_add_string \"name\" \"$name\"\n json_add_string \"path\" \"$file\"\n json_add_int \"size\" \"$(stat -c%s \"$file\" 2>/dev/null || echo 0)\"\n json_close_object\n done\n\n json_close_array\n json_dump\n}\n\n# Perform action with parameters\nperform_action() {\n # Read JSON input from stdin\n read -r input\n json_load \"$input\"\n\n # Extract parameters\n local action_type target\n json_get_var action_type action_type\n json_get_var target target\n json_cleanup\n\n # Validate parameters\n if [ -z \"$action_type\" ]; then\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"message\" \"Action type is required\"\n json_dump\n return 1\n fi\n\n # Perform action based on type\n local result=0\n case \"$action_type\" in\n start)\n # Example: Start a service\n /etc/init.d/\"$target\" start >/dev/null 2>&1\n result=$?\n ;;\n stop)\n # Example: Stop a service\n /etc/init.d/\"$target\" stop >/dev/null 2>&1\n result=$?\n ;;\n restart)\n # Example: Restart a service\n /etc/init.d/\"$target\" restart >/dev/null 2>&1\n result=$?\n ;;\n *)\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"message\" \"Invalid action: $action_type\"\n json_dump\n return 1\n ;;\n esac\n\n # Return result\n json_init\n if [ \"$result\" -eq 0 ]; then\n json_add_boolean \"success\" 1\n json_add_string \"message\" \"Action '$action_type' completed successfully\"\n else\n json_add_boolean \"success\" 0\n json_add_string \"message\" \"Action '$action_type' failed\"\n fi\n json_dump\n}\n\n# Update configuration\nupdate_config() {\n read -r input\n json_load \"$input\"\n\n local key value persist\n json_get_var key key\n json_get_var value value\n json_get_var persist persist\n json_cleanup\n\n # Validate\n if [ -z \"$key\" ] || [ -z \"$value\" ]; then\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"message\" \"Key and value are required\"\n json_dump\n return 1\n fi\n\n # Update UCI config\n uci set <module-name>.general.\"$key\"=\"$value\"\n\n if [ \"$persist\" = \"1\" ]; then\n uci commit <module-name>\n fi\n\n json_init\n json_add_boolean \"success\" 1\n json_add_string \"message\" \"Configuration updated\"\n json_dump\n}\n\n# ============================================================================\n# Main Dispatcher\n# ============================================================================\n\ncase \"$1\" in\n list)\n # List all available methods with their parameters\n cat << 'EOF'\n{\n \"status\": {},\n \"get_data\": {},\n \"perform_action\": {\n \"action_type\": \"string\",\n \"target\": \"string\"\n },\n \"update_config\": {\n \"key\": \"string\",\n \"value\": \"string\",\n \"persist\": 1\n }\n}\nEOF\n ;;\n call)\n # Route to the appropriate method\n case \"$2\" in\n status) status ;;\n get_data) get_data ;;\n perform_action) perform_action ;;\n update_config) update_config ;;\n *)\n # Unknown method\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"error\" \"Unknown method: $2\"\n json_dump\n ;;\n esac\n ;;\nesac\n</code></pre> <p>Key Points: - Always start with <code>#!/bin/sh</code> - Source <code>/lib/functions.sh</code> and <code>/usr/share/libubox/jshn.sh</code> - Use <code>json_init</code>, <code>json_add_*</code>, <code>json_dump</code> for JSON output - Read parameters from stdin using <code>read -r input</code> and <code>json_load</code> - Always validate input parameters - Return proper success/error status - Implement <code>list</code> case to declare all methods and parameters - Implement <code>call</code> case to route to method handlers</p>"},{"location":"code-templates/#menu-json-template","title":"Menu JSON Template","text":"<p>File: <code>root/usr/share/luci/menu.d/luci-app-<module-name>.json</code></p> <pre><code>{\n \"admin/secubox/<category>/<module-name>\": {\n \"title\": \"Module Title\",\n \"order\": 10,\n \"action\": {\n \"type\": \"firstchild\"\n },\n \"depends\": {\n \"acl\": [\"luci-app-<module-name>\"]\n }\n },\n \"admin/secubox/<category>/<module-name>/overview\": {\n \"title\": \"Overview\",\n \"order\": 1,\n \"action\": {\n \"type\": \"view\",\n \"path\": \"<module-name>/overview\"\n }\n },\n \"admin/secubox/<category>/<module-name>/settings\": {\n \"title\": \"Settings\",\n \"order\": 2,\n \"action\": {\n \"type\": \"view\",\n \"path\": \"<module-name>/settings\"\n }\n }\n}\n</code></pre> <p>Categories: - <code>security</code> - Security & monitoring modules (CrowdSec, Auth Guardian) - <code>monitoring</code> - Monitoring modules (Netdata) - <code>network</code> - Network modules (Netifyd, Network Modes, WireGuard) - <code>system</code> - System modules (System Hub) - <code>services</code> - Service modules (CDN Cache, VHost Manager)</p> <p>Key Points: - Menu paths follow <code>admin/secubox/<category>/<module-name></code> - First entry uses <code>\"type\": \"firstchild\"</code> to redirect to first child - Subsequent entries use <code>\"type\": \"view\"</code> with <code>\"path\"</code> matching view file location - Path MUST match: <code>\"path\": \"<module-name>/overview\"</code> \u2192 <code>view/<module-name>/overview.js</code> - Order determines menu position (lower numbers first) - Depends on ACL entry matching package name</p>"},{"location":"code-templates/#acl-json-template","title":"ACL JSON Template","text":"<p>File: <code>root/usr/share/rpcd/acl.d/luci-app-<module-name>.json</code></p> <pre><code>{\n \"luci-app-<module-name>\": {\n \"description\": \"Module Title - Brief Description\",\n \"read\": {\n \"ubus\": {\n \"luci.<module-name>\": [\n \"status\",\n \"get_data\",\n \"get_config\",\n \"list_items\"\n ]\n },\n \"uci\": [\"<module-name>\"]\n },\n \"write\": {\n \"ubus\": {\n \"luci.<module-name>\": [\n \"perform_action\",\n \"update_config\",\n \"delete_item\",\n \"restart_service\"\n ]\n },\n \"uci\": [\"<module-name>\"]\n }\n }\n}\n</code></pre> <p>Key Points: - ACL entry name MUST match package name - <code>read</code> section lists methods that can be called without write permissions - <code>write</code> section lists methods that modify state - ubus object names MUST match RPCD script name (<code>luci.<module-name></code>) - UCI config access can be granted separately - All method names MUST exactly match those defined in RPCD script</p>"},{"location":"code-templates/#css-styling-template","title":"CSS Styling Template","text":"<p>File: <code>htdocs/luci-static/resources/<module-name>/dashboard.css</code></p> <pre><code>/**\n * [Module Name] Dashboard Styles\n * Extends system-hub/common.css design system\n * Version: 1.0.0\n */\n\n/* ============================================================================\n IMPORTANT: Import common.css for design system variables\n ============================================================================ */\n@import url('../system-hub/common.css');\n\n/* ============================================================================\n Module-Specific Styles\n ============================================================================ */\n\n/* Container */\n.module-dashboard {\n padding: 24px;\n background: var(--sh-bg-primary);\n min-height: 100vh;\n}\n\n/* Stats Grid */\n.stats-grid {\n display: grid;\n grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));\n gap: 20px;\n margin: 24px 0;\n}\n\n/* Metric Card */\n.sh-metric-card {\n background: var(--sh-bg-card);\n border: 1px solid var(--sh-border);\n border-radius: 16px;\n padding: 24px;\n transition: all 0.3s ease;\n position: relative;\n overflow: hidden;\n}\n\n.sh-metric-card::before {\n content: '';\n position: absolute;\n top: 0;\n left: 0;\n right: 0;\n height: 3px;\n background: linear-gradient(90deg, var(--sh-primary), var(--sh-primary-end));\n opacity: 0;\n transition: opacity 0.3s ease;\n}\n\n.sh-metric-card:hover {\n transform: translateY(-3px);\n box-shadow: 0 12px 28px var(--sh-hover-shadow);\n}\n\n.sh-metric-card:hover::before {\n opacity: 1;\n}\n\n/* Metric status variants */\n.sh-metric-ok::before {\n background: var(--sh-success);\n opacity: 1;\n}\n\n.sh-metric-warning::before {\n background: var(--sh-warning);\n opacity: 1;\n}\n\n.sh-metric-critical::before {\n background: var(--sh-danger);\n opacity: 1;\n}\n\n/* Metric Header */\n.sh-metric-header {\n display: flex;\n align-items: center;\n gap: 12px;\n margin-bottom: 16px;\n}\n\n.sh-metric-icon {\n font-size: 28px;\n line-height: 1;\n}\n\n.sh-metric-title {\n font-size: 16px;\n font-weight: 600;\n color: var(--sh-text-secondary);\n}\n\n/* Metric Value */\n.sh-metric-value {\n font-size: 40px;\n font-weight: 700;\n font-family: 'JetBrains Mono', monospace;\n color: var(--sh-text-primary);\n margin-bottom: 12px;\n}\n\n/* Metric Progress Bar */\n.sh-metric-progress {\n width: 100%;\n height: 8px;\n background: var(--sh-bg-tertiary);\n border-radius: 4px;\n overflow: hidden;\n margin-bottom: 8px;\n}\n\n.sh-metric-progress-bar {\n height: 100%;\n background: var(--sh-primary);\n transition: width 0.5s ease;\n border-radius: 4px;\n}\n\n/* Metric Details */\n.sh-metric-details {\n font-size: 14px;\n color: var(--sh-text-secondary);\n font-weight: 500;\n}\n\n/* Content Grid */\n.content-grid {\n display: grid;\n grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));\n gap: 24px;\n margin-top: 24px;\n}\n\n/* Component List */\n.component-list {\n display: flex;\n flex-direction: column;\n gap: 12px;\n}\n\n.component-item {\n display: flex;\n align-items: center;\n justify-content: space-between;\n padding: 16px;\n background: var(--sh-bg-secondary);\n border: 1px solid var(--sh-border);\n border-radius: 12px;\n transition: all 0.2s ease;\n position: relative;\n overflow: hidden;\n}\n\n.component-item::before {\n content: '';\n position: absolute;\n top: 0;\n left: 0;\n right: 0;\n height: 3px;\n background: var(--sh-primary);\n opacity: 0;\n transition: opacity 0.3s ease;\n}\n\n.component-item:hover {\n transform: translateX(4px);\n border-color: var(--sh-primary);\n}\n\n.component-item:hover::before {\n opacity: 1;\n}\n\n.component-name {\n font-size: 16px;\n font-weight: 600;\n color: var(--sh-text-primary);\n flex: 1;\n}\n\n.component-status {\n font-size: 14px;\n color: var(--sh-text-secondary);\n margin: 0 16px;\n}\n\n.component-actions {\n display: flex;\n gap: 8px;\n}\n\n/* Quick Actions */\n.quick-actions {\n display: flex;\n flex-wrap: wrap;\n gap: 12px;\n}\n\n/* Activity Log */\n.activity-log {\n display: flex;\n flex-direction: column;\n gap: 12px;\n}\n\n.activity-item {\n display: flex;\n align-items: center;\n gap: 12px;\n padding: 12px;\n background: var(--sh-bg-secondary);\n border-radius: 8px;\n font-size: 14px;\n}\n\n.activity-time {\n font-family: 'JetBrains Mono', monospace;\n color: var(--sh-text-secondary);\n font-size: 12px;\n min-width: 80px;\n}\n\n.activity-text {\n color: var(--sh-text-primary);\n flex: 1;\n}\n\n/* ============================================================================\n Button Variants (Small Size)\n ============================================================================ */\n\n.sh-btn-sm {\n padding: 6px 12px;\n font-size: 12px;\n}\n\n/* ============================================================================\n Responsive Design\n ============================================================================ */\n\n@media (max-width: 768px) {\n .module-dashboard {\n padding: 16px;\n }\n\n .stats-grid,\n .content-grid {\n grid-template-columns: 1fr;\n }\n\n .component-item {\n flex-direction: column;\n align-items: flex-start;\n gap: 12px;\n }\n\n .component-actions {\n width: 100%;\n }\n\n .sh-metric-value {\n font-size: 32px;\n }\n}\n\n/* ============================================================================\n Dark Mode Enhancements\n ============================================================================ */\n\n[data-theme=\"dark\"] .module-dashboard {\n background: var(--sh-bg-primary);\n}\n\n[data-theme=\"dark\"] .component-item,\n[data-theme=\"dark\"] .activity-item {\n background: var(--sh-bg-secondary);\n border-color: var(--sh-border);\n}\n\n[data-theme=\"dark\"] .component-item:hover {\n background: var(--sh-bg-tertiary);\n}\n</code></pre> <p>Key Points: - Always import <code>system-hub/common.css</code> for design system variables - Use CSS variables (<code>var(--sh-*)</code>) instead of hardcoded colors - Support dark mode with <code>[data-theme=\"dark\"]</code> selectors - Use responsive grid layouts (<code>grid-template-columns: repeat(auto-fit, minmax(...))</code>) - Add smooth transitions for better UX - Use JetBrains Mono for numeric values - Follow mobile-first responsive design</p>"},{"location":"code-templates/#complete-implementation-example","title":"Complete Implementation Example","text":"<p>Here's a complete minimal working example for a new module called \"Example Dashboard\":</p>"},{"location":"code-templates/#directory-structure","title":"Directory Structure","text":"<pre><code>luci-app-example-dashboard/\n\u251c\u2500\u2500 Makefile\n\u251c\u2500\u2500 htdocs/luci-static/resources/\n\u2502 \u251c\u2500\u2500 example-dashboard/\n\u2502 \u2502 \u251c\u2500\u2500 api.js\n\u2502 \u2502 \u2514\u2500\u2500 dashboard.css\n\u2502 \u2514\u2500\u2500 view/example-dashboard/\n\u2502 \u2514\u2500\u2500 overview.js\n\u2514\u2500\u2500 root/\n \u2514\u2500\u2500 usr/\n \u251c\u2500\u2500 libexec/rpcd/\n \u2502 \u2514\u2500\u2500 luci.example-dashboard\n \u2514\u2500\u2500 share/\n \u251c\u2500\u2500 luci/menu.d/\n \u2502 \u2514\u2500\u2500 luci-app-example-dashboard.json\n \u2514\u2500\u2500 rpcd/acl.d/\n \u2514\u2500\u2500 luci-app-example-dashboard.json\n</code></pre>"},{"location":"code-templates/#apijs","title":"api.js","text":"<pre><code>'use strict';\n'require baseclass';\n'require rpc';\n\nvar callStatus = rpc.declare({\n object: 'luci.example-dashboard',\n method: 'status',\n expect: {}\n});\n\nreturn baseclass.extend({\n getStatus: callStatus\n});\n</code></pre>"},{"location":"code-templates/#overviewjs","title":"overview.js","text":"<pre><code>'use strict';\n'require view';\n'require example-dashboard/api as API';\n\nreturn view.extend({\n load: function() {\n return API.getStatus();\n },\n\n render: function(data) {\n return E('div', {}, [\n E('link', { 'rel': 'stylesheet', 'href': L.resource('example-dashboard/dashboard.css') }),\n E('h2', {}, 'Example Dashboard'),\n E('p', {}, 'Status: ' + (data.status || 'Unknown'))\n ]);\n },\n\n handleSaveApply: null,\n handleSave: null,\n handleReset: null\n});\n</code></pre>"},{"location":"code-templates/#luciexample-dashboard-rpcd","title":"luci.example-dashboard (RPCD)","text":"<pre><code>#!/bin/sh\n. /usr/share/libubox/jshn.sh\n\nstatus() {\n json_init\n json_add_string \"status\" \"running\"\n json_add_string \"version\" \"1.0.0\"\n json_dump\n}\n\ncase \"$1\" in\n list)\n echo '{\"status\":{}}'\n ;;\n call)\n case \"$2\" in\n status) status ;;\n esac\n ;;\nesac\n</code></pre>"},{"location":"code-templates/#menudluci-app-example-dashboardjson","title":"menu.d/luci-app-example-dashboard.json","text":"<pre><code>{\n \"admin/secubox/monitoring/example-dashboard\": {\n \"title\": \"Example Dashboard\",\n \"order\": 50,\n \"action\": {\n \"type\": \"firstchild\"\n },\n \"depends\": {\n \"acl\": [\"luci-app-example-dashboard\"]\n }\n },\n \"admin/secubox/monitoring/example-dashboard/overview\": {\n \"title\": \"Overview\",\n \"order\": 1,\n \"action\": {\n \"type\": \"view\",\n \"path\": \"example-dashboard/overview\"\n }\n }\n}\n</code></pre>"},{"location":"code-templates/#acldluci-app-example-dashboardjson","title":"acl.d/luci-app-example-dashboard.json","text":"<pre><code>{\n \"luci-app-example-dashboard\": {\n \"description\": \"Example Dashboard\",\n \"read\": {\n \"ubus\": {\n \"luci.example-dashboard\": [\"status\"]\n }\n }\n }\n}\n</code></pre>"},{"location":"code-templates/#dashboardcss","title":"dashboard.css","text":"<pre><code>@import url('../system-hub/common.css');\n\ndiv {\n padding: 20px;\n}\n</code></pre> <p>Installation Steps: 1. Copy files to module directory 2. Set RPCD permissions: <code>chmod +x root/usr/libexec/rpcd/luci.example-dashboard</code> 3. Validate: <code>./secubox-tools/validate-modules.sh</code> 4. Build: <code>./secubox-tools/local-build.sh build luci-app-example-dashboard</code> 5. Deploy: <code>scp build/x86-64/*.ipk root@router:/tmp/</code> 6. Install: <code>ssh root@router \"opkg install /tmp/luci-app-example-dashboard*.ipk && /etc/init.d/rpcd restart\"</code></p>"},{"location":"code-templates/#common-pitfalls-and-solutions","title":"Common Pitfalls and Solutions","text":""},{"location":"code-templates/#1-rpcd-object-not-found-error","title":"1. RPCD \"Object not found\" Error","text":"<p>Error: <code>RPC call to luci.example-dashboard/status failed with error -32000: Object not found</code></p> <p>Solutions: - Check RPCD script name matches ubus object name exactly (including <code>luci.</code> prefix) - Verify RPCD script is executable: <code>chmod +x root/usr/libexec/rpcd/luci.example-dashboard</code> - Restart RPCD service: <code>/etc/init.d/rpcd restart</code> - Check RPCD logs: <code>logread | grep rpcd</code></p>"},{"location":"code-templates/#2-http-404-view-not-found","title":"2. HTTP 404 View Not Found","text":"<p>Error: <code>HTTP error 404 while loading class file '/luci-static/resources/view/example-dashboard/overview.js'</code></p> <p>Solutions: - Verify menu path matches view file location exactly - Menu: <code>\"path\": \"example-dashboard/overview\"</code> \u2192 File: <code>view/example-dashboard/overview.js</code> - Check file permissions: <code>644</code> for CSS/JS files - Clear browser cache</p>"},{"location":"code-templates/#3-acl-permission-denied","title":"3. ACL Permission Denied","text":"<p>Error: Access denied or missing permissions</p> <p>Solutions: - Verify ACL file exists in <code>root/usr/share/rpcd/acl.d/</code> - Check ubus object name in ACL matches RPCD script name - Restart RPCD: <code>/etc/init.d/rpcd restart</code> - Check method is listed in appropriate section (read vs write)</p>"},{"location":"code-templates/#4-css-not-loading","title":"4. CSS Not Loading","text":"<p>Problem: Styles not applied</p> <p>Solutions: - Verify CSS import path: <code>L.resource('example-dashboard/dashboard.css')</code> - Check file permissions: <code>644</code> - Import common.css: <code>@import url('../system-hub/common.css');</code> - Clear browser cache - Check browser console for 404 errors</p>"},{"location":"code-templates/#5-auto-refresh-not-working","title":"5. Auto-Refresh Not Working","text":"<p>Problem: Poll not updating dashboard</p> <p>Solutions: - Verify poll.add() is called in render() method - Check API calls in poll callback return Promises - Ensure updateDashboard() method updates DOM correctly - Use browser console to check for JavaScript errors</p>"},{"location":"code-templates/#validation-checklist","title":"Validation Checklist","text":"<p>Before deploying, always run these checks:</p> <pre><code># 1. Fix permissions\n./secubox-tools/fix-permissions.sh --local\n\n# 2. Validate module structure\n./secubox-tools/validate-modules.sh\n\n# 3. Validate JSON syntax\nfind luci-app-example-dashboard -name \"*.json\" -exec jsonlint {} \\;\n\n# 4. Validate shell scripts\nshellcheck luci-app-example-dashboard/root/usr/libexec/rpcd/*\n\n# 5. Build locally\n./secubox-tools/local-build.sh build luci-app-example-dashboard\n</code></pre> <p>Document Version: 1.0.0 Last Updated: 2025-12-27 Maintainer: CyberMind.fr</p>"},{"location":"codex/","title":"SecuBox Codex Field Manual","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p>"},{"location":"codex/#context-scope","title":"Context & Scope","text":"<p>SecuBox bundles fifteen+ security and network dashboards for OpenWrt with a unified build/validation toolchain and CI that ships <code>.ipk</code>/<code>.apk</code> artifacts automatically (see <code>README.md</code> for the module catalogue and CI badges, <code>README.md:7-34</code>). The documentation set is intentionally layered\u2014<code>DOCS/DOCUMENTATION-INDEX.md</code> routes newcomers, AI assistants, and maintainers to the right depth, so always start requests there before diving into large guides (<code>DOCS/DOCUMENTATION-INDEX.md:15-31</code>).</p> <p>Use this file when you need to brief Codex (or any automation agent) quickly about SecuBox expectations: what standards are immutable, how to craft prompts, where to get help, which decisions shaped today\u2019s tree, and what TODOs should stay in sight during automation runs.</p>"},{"location":"codex/#module-documentation-map","title":"Module & Documentation Map","text":"<ul> <li><code>README.md</code>: one-page overview, compatibility matrix, and \u201cwhat\u2019s new\u201d callouts (<code>README.md:7-34</code>).</li> <li><code>DOCS/QUICK-START.md</code>: critical rules, design tokens, commands, and error playbooks (<code>DOCS/QUICK-START.md:9-195</code>).</li> <li><code>DOCS/DEVELOPMENT-GUIDELINES.md</code>: deep dive into architecture, RPCD, ubus, CSS/JS conventions, and deployment (see summary in <code>DOCS/DOCUMENTATION-INDEX.md:68-82</code>).</li> <li><code>DOCS/MODULE-IMPLEMENTATION-GUIDE.md</code> + <code>DOCS/FEATURE-REGENERATION-PROMPTS.md</code>: regeneration workflow plus ready-to-use prompts for all modules (<code>DOCS/DOCUMENTATION-INDEX.md:102-149</code>).</li> <li><code>DOCS/CODE-TEMPLATES.md</code>: copy/paste-safe scaffolding for LuCI JS, RPCD scripts, and APIs (<code>DOCS/DOCUMENTATION-INDEX.md:153-159</code>).</li> </ul>"},{"location":"codex/#best-practice-snapshot","title":"Best-Practice Snapshot","text":""},{"location":"codex/#non-negotiables-bake-into-every-prompt-or-pr","title":"Non-Negotiables (bake into every prompt or PR)","text":"<ul> <li>RPCD filename must equal the ubus object (prevents <code>-32000 Object not found</code>, <code>DOCS/QUICK-START.md:11-18</code>).</li> <li>Menu JSON <code>path</code> must mirror the view path (avoids 404s, <code>DOCS/QUICK-START.md:20-26</code>).</li> <li>Permissions: RPCD 755, LuCI assets 644, otherwise RPCD won\u2019t execute or LuCI returns 403 (<code>DOCS/QUICK-START.md:28-37</code>).</li> <li>Always run <code>./secubox-tools/validate-modules.sh</code> before opening PRs or tagging builds (reinforced in <code>README.md:18-23</code> and <code>DOCS/QUICK-START.md:122-134</code>).</li> <li>Keep design tokens consistent: dark palette (<code>#0a0a0f</code> base, <code>#6366f1\u2192#8b5cf6</code> gradients), Inter + JetBrains Mono fonts, <code>.sh-*</code>/<code>.sb-*</code> components, and responsive grid widths defined in the quick start (<code>DOCS/QUICK-START.md:74-114</code>).</li> </ul>"},{"location":"codex/#validation-toolchain-flow","title":"Validation & Toolchain Flow","text":"<ol> <li>Permissions Repair (local/remote): <code>./secubox-tools/fix-permissions.sh --local|--remote</code> for automated chmod sanity (<code>DOCS/QUICK-START.md:55-66, 125-127</code>).</li> <li>Full Validation: <code>./secubox-tools/validate-modules.sh</code> (runs seven structural checks including permission scan) (<code>DOCS/QUICK-START.md:122-134,185-189</code>).</li> <li>Module Builds: <code>./secubox-tools/local-build.sh build <module></code> for quick smoke tests or <code>make package/<module>/compile V=s</code> inside SDK (<code>DOCS/QUICK-START.md:135-143</code>).</li> <li>Deploy/Fix: Copy to router via <code>scp</code>, normalize perms, flush <code>luci</code> caches, restart <code>rpcd</code>/<code>uhttpd</code> (<code>DOCS/QUICK-START.md:144-167</code>).</li> <li>Debug: Validate ubus objects, inspect LuCI resources, and tail <code>logread</code> immediately after deployment (<code>DOCS/QUICK-START.md:156-167</code>).</li> </ol>"},{"location":"codex/#design-ux-reminders","title":"Design & UX Reminders","text":"<ul> <li>Stats tiles minimum 130\u202fpx width, metrics 240\u202fpx, detail cards 300\u202fpx: encode these CSS grid rules to keep dashboards fluid on 720p+ viewports (<code>DOCS/QUICK-START.md:105-114</code>).</li> <li>Buttons, tabs, and cards expose <code>.sh-</code> utility classes; prefer gradient borders and neon states over inline styles for maintainability (same section).</li> <li>Align copy with README taxonomy (Core Control, Security & Monitoring, Network Intelligence, etc.) so documentation and UI stay in sync (<code>README.md:37-152</code> excerpt).</li> </ul>"},{"location":"codex/#prompt-playbook","title":"Prompt Playbook","text":"<p>When drafting Codex/LLM prompts, supply enough structure so the assistant can reuse existing patterns instead of inventing them. Reuse this outline:</p> <pre><code>Context:\n- Target module + file(s) + desired change.\n- Any relevant excerpts from CODE-TEMPLATES or existing JS/RPCD files.\n\nRequirements:\n- Restate non-negotiables (RPCD naming, menu path, permissions, design tokens).\n- Mention validation commands Codex should run or assume.\n- Call out API endpoints, ubus objects, or metrics to surface.\n\nDeliverables:\n- Files to touch (path + rationale).\n- Expected tests/validations (e.g., run ./secubox-tools/validate-modules.sh).\n- UX cues (colors, grid sizes, component classes) referencing QUICK-START.\n\nGuardrails:\n- Note TODO items or documentation standards (version headers, cross-links, etc.).\n- Remind Codex where to log changes (README, module changelog, etc.).\n</code></pre> <p>Pair the template with module-specific prompts from <code>DOCS/FEATURE-REGENERATION-PROMPTS.md</code> and the workflow from <code>DOCS/MODULE-IMPLEMENTATION-GUIDE.md</code> (<code>DOCS/DOCUMENTATION-INDEX.md:102-149</code>). That combination lets Codex inherit existing layout structures, RPCD shells, and API modules without brittle guesswork.</p>"},{"location":"codex/#help-troubleshooting","title":"Help & Troubleshooting","text":"<ul> <li>Pre-deploy Sanity: Run the overlay disk/permission SSH checks before copying files; they are scripted inside the quick start so you can paste directly into terminal sessions (<code>DOCS/QUICK-START.md:40-53</code>).</li> <li>Common Error Fixes: Keep the quick fixes near: HTTP 403 (chmod assets), \u201cNo space left\u201d (purge <code>/tmp/*.ipk</code> and backups), ubus <code>-32000</code> (chmod 755 + ubus list). Automate via <code>secubox-tools</code> whenever possible (<code>DOCS/QUICK-START.md:55-70,171-180</code>).</li> <li>Design Drift: If CSS feels inconsistent, cross-check against the palette/fonts/components found in this manual and in the design section of the quick start (<code>DOCS/QUICK-START.md:74-114</code>).</li> <li>Need Examples?: Pull actual JS/RPCD snippets from <code>DOCS/CODE-TEMPLATES.md</code> or live modules under <code>luci-app-*</code> to keep generated code idiomatic (<code>DOCS/DOCUMENTATION-INDEX.md:153-159</code>).</li> <li>Still Blocked?: <code>DOCS/DEVELOPMENT-GUIDELINES.md</code> holds the long-form reasoning for every standard; cite relevant sections when escalating issues so maintainers see the source of truth quickly (<code>DOCS/DOCUMENTATION-INDEX.md:68-82</code>).</li> </ul>"},{"location":"codex/#history","title":"History","text":"<ul> <li>2025-12-26 \u2013 Full Dev Guides Released: README announces the arrival of the comprehensive dev guides set (README badge section, <code>README.md:7-16</code>).</li> <li>2025-12-27 \u2013 Documentation Index v1.0.0: Central index formalized the document map and AI workflow branches (<code>DOCS/DOCUMENTATION-INDEX.md:1-31</code>).</li> <li>2025-12-28 \u2013 Documentation Improvement Plan: <code>TODO-ANALYSE.md</code> generated to coordinate versioning, cross-links, and archival tasks (<code>TODO-ANALYSE.md:1-34,71-150</code>).</li> <li>2025-12-28 \u2013 Codex Manual Drafted: This CODEX field manual formalizes how automation agents should operate going forward.</li> </ul>"},{"location":"codex/#todo-radar-keep-codex-aligned","title":"TODO Radar (keep Codex aligned)","text":"<ol> <li>Standardize version headers & dates \u2013 ensure every <code>.md</code> shows <code>Version/Last Updated/Status</code> with consistent <code>YYYY-MM-DD</code> formatting; DOCUMENTATION-INDEX must describe the policy once updates land (<code>TODO-ANALYSE.md:24-68</code>).</li> <li>Add \u201cSee Also\u201d cross-links \u2013 wire QUICK-START, PERMISSIONS-GUIDE, VALIDATION-GUIDE, and other quick refs back to their parent guides and vice-versa so AI/users don\u2019t get orphaned instructions (<code>TODO-ANALYSE.md:71-116</code>).</li> <li>Archive historical docs \u2013 create <code>docs/archive/</code>, move outdated references (COMPLETION_REPORT, MODULE-ENABLE-DISABLE-DESIGN, BUILD_ISSUES, etc.), and drop an archive README describing contents (<code>TODO-ANALYSE.md:120-153</code>).</li> <li>Future work (Monthly/Quarterly) \u2013 new diagrams, TESTING/SECURITY/PERFORMANCE guides, automation for doc freshness, and i18n decisions are queued later in <code>TODO-ANALYSE.md</code>; mention them when prompts may impact scope or format downstream.</li> </ol> <p>Codex should treat the TODOs above as guardrails: if a task touches documentation, prefer solutions that inch us toward these goals (e.g., add version headers while editing a doc, or cross-link when touching quick references).</p>"},{"location":"codex/#quick-reference-checklist-for-codex-runs","title":"Quick Reference Checklist for Codex Runs","text":"<ul> <li> Confirm the request references the right guide/template to minimize hallucinations (<code>DOCS/DOCUMENTATION-INDEX.md</code> paths).</li> <li> Copy/paste the non-negotiables + validation flow into the prompt.</li> <li> State which TODO radar items the change advances (or at least does not regress).</li> <li> Cite commands/scripts to run post-change.</li> <li> Capture findings in PR/commit descriptions referencing this CODEX manual when relevant.</li> </ul> <p>Use this living manual as both a pre-flight briefing and a debrief log for automation work. Update it whenever the standards above evolve so every future Codex session starts with the correct mental model.</p>"},{"location":"development-guidelines/","title":"SecuBox & System Hub - Development Guidelines","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active Audience: D\u00e9veloppeurs, IA assistants, mainteneurs</p> <p>Ce document d\u00e9finit les standards, bonnes pratiques et validations obligatoires pour le d\u00e9veloppement de modules SecuBox et System Hub dans l'\u00e9cosyst\u00e8me OpenWrt LuCI.</p>"},{"location":"development-guidelines/#table-des-matieres","title":"Table des mati\u00e8res","text":"<ol> <li>Design System & UI Guidelines</li> <li>Architecture & Naming Conventions</li> <li>RPCD & ubus Best Practices</li> <li>ACL & Permissions</li> <li>JavaScript Patterns</li> <li>CSS/Styling Standards</li> <li>Common Errors & Solutions</li> <li>Validation Checklist</li> <li>Deployment Procedures</li> <li>AI Assistant Context Files</li> </ol>"},{"location":"development-guidelines/#design-system-ui-guidelines","title":"Design System & UI Guidelines","text":""},{"location":"development-guidelines/#color-palette-demo-inspired","title":"Color Palette (Demo-inspired)","text":"<p>IMPORTANT: Toujours utiliser la palette d\u00e9finie dans <code>system-hub/common.css</code></p>"},{"location":"development-guidelines/#dark-mode-primary-recommended","title":"Dark Mode (Primary - Recommended)","text":"<pre><code>--sh-text-primary: #fafafa;\n--sh-text-secondary: #a0a0b0;\n--sh-bg-primary: #0a0a0f; /* Fond principal (noir profond) */\n--sh-bg-secondary: #12121a; /* Fond cartes/sections */\n--sh-bg-tertiary: #1a1a24; /* Fond hover/actif */\n--sh-bg-card: #12121a;\n--sh-border: #2a2a35;\n--sh-primary: #6366f1; /* Indigo */\n--sh-primary-end: #8b5cf6; /* Violet (pour d\u00e9grad\u00e9s) */\n--sh-success: #22c55e; /* Vert */\n--sh-danger: #ef4444; /* Rouge */\n--sh-warning: #f59e0b; /* Orange */\n</code></pre>"},{"location":"development-guidelines/#light-mode-secondary","title":"Light Mode (Secondary)","text":"<pre><code>--sh-text-primary: #0f172a;\n--sh-text-secondary: #475569;\n--sh-bg-primary: #ffffff;\n--sh-bg-secondary: #f8fafc;\n--sh-bg-tertiary: #f1f5f9;\n--sh-bg-card: #ffffff;\n--sh-border: #e2e8f0;\n</code></pre> <p>\u2705 TOUJOURS utiliser les CSS variables - Ne JAMAIS hardcoder les couleurs.</p>"},{"location":"development-guidelines/#typography","title":"Typography","text":""},{"location":"development-guidelines/#fonts-stack","title":"Fonts Stack","text":"<pre><code>/* Texte g\u00e9n\u00e9ral */\nfont-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;\n\n/* Valeurs num\u00e9riques, IDs, code */\nfont-family: 'JetBrains Mono', 'Courier New', monospace;\n</code></pre> <p>Import requis (ajout\u00e9 dans common.css): <pre><code>@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap');\n</code></pre></p>"},{"location":"development-guidelines/#font-sizes","title":"Font Sizes","text":"<pre><code>/* Titres */\n--sh-title-xl: 28px; /* Page titles */\n--sh-title-lg: 20px; /* Card titles */\n--sh-title-md: 16px; /* Section headers */\n\n/* Texte */\n--sh-text-base: 14px; /* Body text */\n--sh-text-sm: 13px; /* Labels, meta */\n--sh-text-xs: 11px; /* Uppercase labels */\n\n/* Valeurs */\n--sh-value-xl: 40px; /* Large metrics */\n--sh-value-lg: 32px; /* Stats overview */\n--sh-value-md: 28px; /* Badges */\n</code></pre>"},{"location":"development-guidelines/#component-patterns","title":"Component Patterns","text":""},{"location":"development-guidelines/#component-hierarchy","title":"Component Hierarchy","text":"<p>The following diagram shows the standard page structure and component relationships:</p> <pre><code>graph TB\n PAGE[Page Container<br/>.module-dashboard] --> HEADER[sh-page-header]\n PAGE --> CONTENT[sh-content]\n\n HEADER --> TITLE_SECTION[Title Section<br/>div]\n HEADER --> STATS[sh-stats-grid]\n\n TITLE_SECTION --> TITLE[sh-page-title<br/>gradient text]\n TITLE_SECTION --> SUBTITLE[sh-page-subtitle]\n\n STATS --> BADGE1[sh-stat-badge]\n STATS --> BADGE2[sh-stat-badge]\n STATS --> BADGE3[...]\n\n BADGE1 --> VALUE1[sh-stat-value<br/>monospace font]\n BADGE1 --> LABEL1[sh-stat-label<br/>uppercase]\n\n CONTENT --> TABS[sh-filter-tabs]\n CONTENT --> CARD_GRID[Card Grid<br/>grid layout]\n\n TABS --> TAB1[sh-filter-tab<br/>active]\n TABS --> TAB2[sh-filter-tab]\n\n CARD_GRID --> CARD1[sh-card]\n CARD_GRID --> CARD2[sh-card-success]\n CARD_GRID --> CARD3[sh-card-danger]\n\n CARD1 --> CH1[sh-card-header]\n CARD1 --> CB1[sh-card-body]\n\n CH1 --> CT1[sh-card-title]\n CT1 --> ICON1[sh-card-title-icon]\n\n CB1 --> BUTTONS[Button Group]\n CB1 --> INFO[Info Rows]\n\n BUTTONS --> BTN1[sh-btn<br/>sh-btn-primary]\n BUTTONS --> BTN2[sh-btn<br/>sh-btn-secondary]\n\n style PAGE fill:#0a0a0f,color:#fafafa,stroke:#6366f1,stroke-width:3px\n style HEADER fill:#12121a,color:#fafafa,stroke:#6366f1,stroke-width:2px\n style CONTENT fill:#12121a,color:#fafafa,stroke:#6366f1,stroke-width:2px\n style CARD1 fill:#12121a,color:#fafafa,stroke:#6366f1,stroke-width:2px\n style CARD2 fill:#12121a,color:#fafafa,stroke:#22c55e,stroke-width:2px\n style CARD3 fill:#12121a,color:#fafafa,stroke:#ef4444,stroke-width:2px\n style TITLE fill:#6366f1,color:#fff\n style BTN1 fill:#6366f1,color:#fff\n style VALUE1 fill:#8b5cf6,color:#fff</code></pre> <p>Component Categories: 1. Layout Containers: Page wrapper, header, content sections 2. Typography: Titles with gradient effects, subtitles, labels 3. Data Display: Stat badges with monospace values, cards with borders 4. Navigation: Filter tabs, nav tabs (sticky) 5. Interactive: Buttons with gradients and hover effects</p> <p>Styling Rules: - Cards: 3px top border (gradient on hover, or colored for status) - Stat Badges: Minimum 130px width, monospace font for values - Buttons: Gradient backgrounds, shadow on hover, smooth transitions - Tabs: Active state with gradient background and glow - Grid Layouts: Auto-fit with minimums (130px, 240px, or 300px)</p>"},{"location":"development-guidelines/#1-page-header-standard","title":"1. Page Header (Standard)","text":"<p>REQUIREMENT: Every module view MUST begin with this compact <code>.sh-page-header</code>. Do not introduce bespoke hero sections or oversized banners; the header keeps height predictable (title + subtitle on the left, stats on the right) and guarantees consistency across SecuBox dashboards. If no stats are needed, keep the container but supply an empty <code>.sh-stats-grid</code> for future metrics.</p> <p>Slim variant: When the page only needs 2\u20113 metrics, use <code>.sh-page-header-lite</code> + <code>.sh-header-chip</code> (see <code>luci-app-vhost-manager</code> and <code>luci-app-secubox</code> settings). Chips carry an emoji/icon, a tiny label, and the value; colors (<code>.success</code>, <code>.danger</code>, <code>.warn</code>) communicate state. This variant replaces the bulky hero blocks from older demos.</p> <p>Version chip: Always expose the package version from the RPC backend (read from <code>/usr/lib/opkg/info/<pkg>.control</code>) and display it as the first chip (<code>icon: \ud83c\udff7\ufe0f</code>). That keeps the UI and <code>PKG_VERSION</code> in sync without hunting for hard-coded strings.</p> <p>HTML Structure: <pre><code>E('div', { 'class': 'sh-page-header' }, [\n E('div', {}, [\n E('h2', { 'class': 'sh-page-title' }, [\n E('span', { 'class': 'sh-page-title-icon' }, '\ud83c\udfaf'),\n 'Page Title'\n ]),\n E('p', { 'class': 'sh-page-subtitle' }, 'Description of the page')\n ]),\n E('div', { 'class': 'sh-stats-grid' }, [\n // Stats badges here\n ])\n])\n</code></pre></p> <p>CSS Classes: - <code>.sh-page-header</code> - Container with flex layout - <code>.sh-page-title</code> - Gradient text effect - <code>.sh-page-title-icon</code> - Icon (no gradient) - <code>.sh-page-subtitle</code> - Secondary text - <code>.sh-stats-grid</code> - Grid pour badges (130px min)</p>"},{"location":"development-guidelines/#2-stats-badges","title":"2. Stats Badges","text":"<p>R\u00c8GLE: Minimum 130px, police monospace pour valeurs</p> <pre><code>E('div', { 'class': 'sh-stat-badge' }, [\n E('div', { 'class': 'sh-stat-value' }, '92'),\n E('div', { 'class': 'sh-stat-label' }, 'CPU %')\n])\n</code></pre> <p>Grid Layout: <pre><code>.sh-stats-grid {\n display: grid;\n grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));\n gap: 12px;\n}\n</code></pre></p>"},{"location":"development-guidelines/#3-cards-avec-bordure-coloree","title":"3. Cards avec bordure color\u00e9e","text":"<p>OBLIGATOIRE: Toutes les cards doivent avoir une bordure top de 3px</p> <pre><code>E('div', { 'class': 'sh-card sh-card-success' }, [\n E('div', { 'class': 'sh-card-header' }, [\n E('h3', { 'class': 'sh-card-title' }, [\n E('span', { 'class': 'sh-card-title-icon' }, '\u2699\ufe0f'),\n 'Card Title'\n ])\n ]),\n E('div', { 'class': 'sh-card-body' }, [\n // Content\n ])\n])\n</code></pre> <p>Variants de bordure: - <code>.sh-card</code> - Bordure gradient (visible au hover) - <code>.sh-card-success</code> - Bordure verte permanente - <code>.sh-card-danger</code> - Bordure rouge permanente - <code>.sh-card-warning</code> - Bordure orange permanente</p>"},{"location":"development-guidelines/#4-buttons","title":"4. Buttons","text":"<p>Gradient buttons (preferred): <pre><code>E('button', { 'class': 'sh-btn sh-btn-primary' }, 'Primary Action')\nE('button', { 'class': 'sh-btn sh-btn-success' }, 'Success Action')\nE('button', { 'class': 'sh-btn sh-btn-danger' }, 'Danger Action')\nE('button', { 'class': 'sh-btn sh-btn-secondary' }, 'Secondary Action')\n</code></pre></p> <p>Tous les buttons doivent avoir: - Shadow effect (d\u00e9j\u00e0 dans CSS) - Hover animation (translateY(-2px)) - Transition smooth (0.3s cubic-bezier)</p>"},{"location":"development-guidelines/#5-filter-tabs","title":"5. Filter Tabs","text":"<pre><code>E('div', { 'class': 'sh-filter-tabs' }, [\n E('div', {\n 'class': 'sh-filter-tab active',\n 'data-filter': 'all'\n }, [\n E('span', { 'class': 'sh-tab-icon' }, '\ud83d\udccb'),\n E('span', { 'class': 'sh-tab-label' }, 'All')\n ])\n])\n</code></pre> <p>Active tab styling: - Background: gradient indigo-violet - Color: white - Box-shadow avec glow</p>"},{"location":"development-guidelines/#grid-systems","title":"Grid Systems","text":""},{"location":"development-guidelines/#stats-overview-compact","title":"Stats Overview (Compact)","text":"<pre><code>grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));\ngap: 16px;\n</code></pre>"},{"location":"development-guidelines/#metric-cards-medium","title":"Metric Cards (Medium)","text":"<pre><code>grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));\ngap: 20px;\n</code></pre>"},{"location":"development-guidelines/#info-cards-large","title":"Info Cards (Large)","text":"<pre><code>grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));\ngap: 20px;\n</code></pre>"},{"location":"development-guidelines/#gradient-effects","title":"Gradient Effects","text":""},{"location":"development-guidelines/#gradient-text-titles","title":"Gradient Text (Titles)","text":"<pre><code>background: linear-gradient(135deg, var(--sh-primary), var(--sh-primary-end));\n-webkit-background-clip: text;\n-webkit-text-fill-color: transparent;\nbackground-clip: text;\n</code></pre> <p>Utiliser: <code>.sh-gradient-text</code> class ou <code>.sh-page-title</code></p>"},{"location":"development-guidelines/#gradient-backgrounds-buttons-badges","title":"Gradient Backgrounds (Buttons, Badges)","text":"<pre><code>background: linear-gradient(135deg, var(--sh-primary), var(--sh-primary-end));\n</code></pre>"},{"location":"development-guidelines/#gradient-borders-top","title":"Gradient Borders (Top)","text":"<pre><code>/* 3px top border avec d\u00e9grad\u00e9 */\n.element::before {\n content: '';\n position: absolute;\n top: 0;\n left: 0;\n right: 0;\n height: 3px;\n background: linear-gradient(90deg, var(--sh-primary), var(--sh-primary-end));\n}\n</code></pre>"},{"location":"development-guidelines/#animation-standards","title":"Animation Standards","text":""},{"location":"development-guidelines/#hover-effects","title":"Hover Effects","text":"<pre><code>transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);\ntransform: translateY(-3px); /* Cards */\ntransform: translateY(-2px); /* Buttons, badges */\n</code></pre>"},{"location":"development-guidelines/#shadow-progression","title":"Shadow Progression","text":"<pre><code>/* Default */\nbox-shadow: none;\n\n/* Hover - Subtle */\nbox-shadow: 0 8px 20px var(--sh-shadow);\n\n/* Hover - Pronounced */\nbox-shadow: 0 12px 28px var(--sh-hover-shadow);\n\n/* Button Hover */\nbox-shadow: 0 8px 20px rgba(99, 102, 241, 0.5);\n</code></pre>"},{"location":"development-guidelines/#architecture-naming-conventions","title":"Architecture & Naming Conventions","text":""},{"location":"development-guidelines/#system-architecture-overview","title":"System Architecture Overview","text":"<p>The following diagram illustrates the complete data flow from browser JavaScript to system backend:</p> <pre><code>graph TB\n subgraph \"Browser\"\n UI[JavaScript View<br/>view/module/overview.js]\n API[API Module<br/>module/api.js]\n end\n\n subgraph \"LuCI Framework\"\n RPC[RPC Layer<br/>L.rpc.declare]\n UHTTPD[uhttpd<br/>Web Server]\n end\n\n subgraph \"Backend Services\"\n RPCD[RPCD Daemon]\n SCRIPT[RPCD Script<br/>/usr/libexec/rpcd/luci.module-name]\n UBUS[ubus Message Bus]\n end\n\n subgraph \"System Layer\"\n UCI[UCI Configuration]\n SYS[System Services<br/>init.d scripts]\n FS[Filesystem<br/>proc, sys, etc]\n end\n\n UI -->|\"API.getStatus()\"| API\n API -->|\"rpc.declare({ object: 'luci.module' })\"| RPC\n RPC -->|\"HTTP POST /ubus\"| UHTTPD\n UHTTPD -->|\"call method\"| RPCD\n RPCD -->|\"execute script\"| SCRIPT\n SCRIPT -->|\"ubus call\"| UBUS\n UBUS -->|\"read/write\"| UCI\n UBUS -->|\"control\"| SYS\n SCRIPT -->|\"read metrics\"| FS\n\n style UI fill:#6366f1,color:#fff,stroke:#4f46e5\n style API fill:#8b5cf6,color:#fff,stroke:#7c3aed\n style SCRIPT fill:#22c55e,color:#fff,stroke:#16a34a\n style RPCD fill:#f59e0b,color:#fff,stroke:#d97706\n style UCI fill:#ef4444,color:#fff,stroke:#dc2626</code></pre> <p>Key Components: 1. Browser Layer: JavaScript views and API modules handle UI and data requests 2. LuCI Framework: RPC layer translates JavaScript calls to ubus protocol 3. Backend Services: RPCD executes shell scripts via ubus message bus 4. System Layer: UCI configs, system services, and filesystem provide data</p> <p>Critical Naming Rule: The RPCD script name MUST match the <code>object</code> parameter in JavaScript's <code>rpc.declare()</code>.</p>"},{"location":"development-guidelines/#critical-rpcd-script-naming","title":"CRITICAL: RPCD Script Naming","text":"<p>R\u00c8GLE ABSOLUE: Le nom du fichier RPCD DOIT correspondre EXACTEMENT au nom de l'objet ubus dans JavaScript.</p>"},{"location":"development-guidelines/#correct","title":"\u2705 CORRECT:","text":"<p>JavaScript: <pre><code>var callStatus = rpc.declare({\n object: 'luci.system-hub', // \u2190 Nom objet\n method: 'getHealth'\n});\n</code></pre></p> <p>Fichier RPCD: <pre><code>root/usr/libexec/rpcd/luci.system-hub # \u2190 EXACT MATCH\n</code></pre></p>"},{"location":"development-guidelines/#incorrect-causes-derreur-32000","title":"\u274c INCORRECT (Causes d'erreur -32000):","text":"<pre><code># Mauvais - manque le pr\u00e9fixe\nroot/usr/libexec/rpcd/system-hub\n\n# Mauvais - underscore au lieu de tiret\nroot/usr/libexec/rpcd/luci.system_hub\n\n# Mauvais - nom diff\u00e9rent\nroot/usr/libexec/rpcd/systemhub\n</code></pre>"},{"location":"development-guidelines/#menu-path-conventions","title":"Menu Path Conventions","text":"<p>R\u00c8GLE: Les chemins dans menu.d/*.json doivent correspondre EXACTEMENT aux fichiers de vue.</p>"},{"location":"development-guidelines/#correct_1","title":"\u2705 CORRECT:","text":"<p>Menu JSON: <pre><code>{\n \"action\": {\n \"type\": \"view\",\n \"path\": \"system-hub/overview\"\n }\n}\n</code></pre></p> <p>Fichier de vue: <pre><code>htdocs/luci-static/resources/view/system-hub/overview.js\n</code></pre></p>"},{"location":"development-guidelines/#incorrect-causes-404","title":"\u274c INCORRECT (Causes 404):","text":"<p>Menu: <code>\"path\": \"system-hub/overview\"</code> mais fichier: <code>view/systemhub/overview.js</code></p>"},{"location":"development-guidelines/#prefixes-standards","title":"Prefixes Standards","text":"Type Prefix Exemple ubus objects <code>luci.</code> <code>luci.system-hub</code> CSS classes <code>sh-</code> (System Hub) ou <code>sb-</code> (SecuBox) <code>.sh-page-header</code> CSS variables <code>--sh-</code> <code>--sh-primary</code> JavaScript modules Nom du module <code>system-hub/api.js</code>"},{"location":"development-guidelines/#file-structure-template","title":"File Structure Template","text":"<pre><code>luci-app-<module-name>/\n\u251c\u2500\u2500 Makefile\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 htdocs/luci-static/resources/\n\u2502 \u251c\u2500\u2500 view/<module-name>/\n\u2502 \u2502 \u251c\u2500\u2500 overview.js # Page principale\n\u2502 \u2502 \u251c\u2500\u2500 settings.js # Configuration\n\u2502 \u2502 \u2514\u2500\u2500 *.js # Autres vues\n\u2502 \u2514\u2500\u2500 <module-name>/\n\u2502 \u251c\u2500\u2500 api.js # RPC client\n\u2502 \u251c\u2500\u2500 theme.js # Theme helpers (optionnel)\n\u2502 \u251c\u2500\u2500 common.css # Styles partag\u00e9s\n\u2502 \u2514\u2500\u2500 *.css # Styles sp\u00e9cifiques\n\u2514\u2500\u2500 root/\n \u251c\u2500\u2500 usr/\n \u2502 \u251c\u2500\u2500 libexec/rpcd/\n \u2502 \u2502 \u2514\u2500\u2500 luci.<module-name> # \u26a0\ufe0f MUST match ubus object\n \u2502 \u2514\u2500\u2500 share/\n \u2502 \u251c\u2500\u2500 luci/menu.d/\n \u2502 \u2502 \u2514\u2500\u2500 luci-app-<module-name>.json\n \u2502 \u2514\u2500\u2500 rpcd/acl.d/\n \u2502 \u2514\u2500\u2500 luci-app-<module-name>.json\n \u2514\u2500\u2500 etc/config/<module-name> (optionnel)\n</code></pre>"},{"location":"development-guidelines/#rpcd-ubus-best-practices","title":"RPCD & ubus Best Practices","text":""},{"location":"development-guidelines/#rpcd-script-template-shell","title":"RPCD Script Template (Shell)","text":"<p>Fichier: <code>root/usr/libexec/rpcd/luci.<module-name></code></p> <pre><code>#!/bin/sh\n# RPCD backend for <module-name>\n# ubus object: luci.<module-name>\n\ncase \"$1\" in\n list)\n # Liste des m\u00e9thodes disponibles\n echo '{\n \"getStatus\": {},\n \"getHealth\": {},\n \"getServices\": {}\n }'\n ;;\n call)\n case \"$2\" in\n getStatus)\n # TOUJOURS retourner du JSON valide\n printf '{\"enabled\": true, \"version\": \"1.0.0\"}\\n'\n ;;\n getHealth)\n # Lire les m\u00e9triques syst\u00e8me\n cpu_usage=$(top -bn1 | grep \"CPU:\" | awk '{print $2}' | sed 's/%//')\n mem_total=$(free | grep Mem | awk '{print $2}')\n mem_used=$(free | grep Mem | awk '{print $3}')\n\n printf '{\n \"cpu\": {\"usage\": %s},\n \"memory\": {\"total_kb\": %s, \"used_kb\": %s}\n }\\n' \"$cpu_usage\" \"$mem_total\" \"$mem_used\"\n ;;\n getServices)\n # Exemple avec services\n services='[]'\n for service in /etc/init.d/*; do\n # Build JSON array\n :\n done\n echo \"$services\"\n ;;\n *)\n echo '{\"error\": \"Method not found\"}'\n exit 1\n ;;\n esac\n ;;\nesac\n</code></pre>"},{"location":"development-guidelines/#rpcd-script-validation","title":"RPCD Script Validation","text":"<p>CHECKLIST OBLIGATOIRE:</p> <ol> <li>\u2705 Fichier ex\u00e9cutable: <code>chmod +x root/usr/libexec/rpcd/luci.<module-name></code></li> <li>\u2705 Shebang pr\u00e9sent: <code>#!/bin/sh</code></li> <li>\u2705 Structure case/esac correcte</li> <li>\u2705 M\u00e9thode <code>list</code> retourne JSON avec toutes les m\u00e9thodes</li> <li>\u2705 M\u00e9thode <code>call</code> g\u00e8re tous les cas</li> <li>\u2705 Toujours retourner du JSON valide</li> <li>\u2705 Pas de <code>echo</code> de debug (comment\u00e9s en prod)</li> <li>\u2705 Gestion d'erreur pour m\u00e9thodes inconnues</li> </ol>"},{"location":"development-guidelines/#testing-rpcd-scripts","title":"Testing RPCD Scripts","text":"<p>Sur le routeur:</p> <pre><code># Test direct\n/usr/libexec/rpcd/luci.system-hub list\n\n# Via ubus\nubus list luci.system-hub\nubus call luci.system-hub getStatus\n\n# Restart RPCD apr\u00e8s modification\n/etc/init.d/rpcd restart\n</code></pre>"},{"location":"development-guidelines/#common-rpcd-errors","title":"Common RPCD Errors","text":""},{"location":"development-guidelines/#error-object-not-found-32000","title":"Error: \"Object not found\" (-32000)","text":"<p>Cause: Nom du fichier RPCD ne correspond pas \u00e0 l'objet ubus</p> <p>Solution: <pre><code># V\u00e9rifier le nom dans JS\ngrep -r \"object:\" htdocs/luci-static/resources/view/ --include=\"*.js\"\n\n# Renommer le fichier RPCD pour correspondre\nmv root/usr/libexec/rpcd/wrong-name root/usr/libexec/rpcd/luci.correct-name\n</code></pre></p>"},{"location":"development-guidelines/#error-method-not-found-32601","title":"Error: \"Method not found\" (-32601)","text":"<p>Cause: M\u00e9thode non d\u00e9clar\u00e9e dans <code>list</code> ou non impl\u00e9ment\u00e9e dans <code>call</code></p> <p>Solution: <pre><code># V\u00e9rifier que la m\u00e9thode est dans les deux blocs\ngrep \"getStatus\" root/usr/libexec/rpcd/luci.*\n</code></pre></p>"},{"location":"development-guidelines/#error-invalid-json-returned","title":"Error: Invalid JSON returned","text":"<p>Cause: Output RPCD n'est pas du JSON valide</p> <p>Solution: <pre><code># Tester le JSON\n/usr/libexec/rpcd/luci.module-name call getStatus | jsonlint\n\n# Utiliser printf au lieu de echo pour le JSON\nprintf '{\"key\": \"%s\"}\\n' \"$value\"\n</code></pre></p>"},{"location":"development-guidelines/#acl-permissions","title":"ACL & Permissions","text":""},{"location":"development-guidelines/#acl-file-template","title":"ACL File Template","text":"<p>Fichier: <code>root/usr/share/rpcd/acl.d/luci-app-<module-name>.json</code></p> <pre><code>{\n \"luci-app-<module-name>\": {\n \"description\": \"Grant access to <Module Name>\",\n \"read\": {\n \"ubus\": {\n \"luci.<module-name>\": [\n \"getStatus\",\n \"getHealth\",\n \"getServices\"\n ]\n },\n \"uci\": [\n \"<module-name>\"\n ]\n },\n \"write\": {\n \"ubus\": {\n \"luci.<module-name>\": [\n \"setConfig\",\n \"restartService\"\n ]\n },\n \"uci\": [\n \"<module-name>\"\n ]\n }\n }\n}\n</code></pre>"},{"location":"development-guidelines/#acl-best-practices","title":"ACL Best Practices","text":"<ol> <li>S\u00e9paration read/write: Ne donnez que les permissions n\u00e9cessaires</li> <li>Liste explicite: Listez toutes les m\u00e9thodes ubus utilis\u00e9es</li> <li>UCI access: Ajoutez les configs UCI dans <code>read</code> et <code>write</code></li> <li>Validation JSON: Toujours valider avec <code>jsonlint</code></li> </ol>"},{"location":"development-guidelines/#common-acl-errors","title":"Common ACL Errors","text":""},{"location":"development-guidelines/#error-access-denied","title":"Error: \"Access denied\"","text":"<p>Cause: M\u00e9thode ubus pas dans ACL</p> <p>Solution: <pre><code>{\n \"read\": {\n \"ubus\": {\n \"luci.system-hub\": [\n \"getHealth\" // \u2190 Ajouter la m\u00e9thode manquante\n ]\n }\n }\n}\n</code></pre></p>"},{"location":"development-guidelines/#error-uci-config-not-accessible","title":"Error: \"UCI config not accessible\"","text":"<p>Cause: Config UCI pas dans ACL</p> <p>Solution: <pre><code>{\n \"read\": {\n \"uci\": [\n \"system-hub\" // \u2190 Ajouter le config\n ]\n }\n}\n</code></pre></p>"},{"location":"development-guidelines/#javascript-patterns","title":"JavaScript Patterns","text":""},{"location":"development-guidelines/#api-module-template","title":"API Module Template","text":"<p>Fichier: <code>htdocs/luci-static/resources/<module-name>/api.js</code></p> <pre><code>'use strict';\n'require rpc';\n'require uci';\n\nreturn L.Class.extend({\n // D\u00e9clarer les appels RPC\n callGetStatus: rpc.declare({\n object: 'luci.<module-name>',\n method: 'getStatus',\n expect: { }\n }),\n\n callGetHealth: rpc.declare({\n object: 'luci.<module-name>',\n method: 'getHealth',\n expect: { }\n }),\n\n // M\u00e9thodes wrapper avec gestion d'erreur\n getStatus: function() {\n return this.callGetStatus().catch(function(err) {\n console.error('Failed to get status:', err);\n return { enabled: false, error: err.message };\n });\n },\n\n getHealth: function() {\n return this.callGetHealth().catch(function(err) {\n console.error('Failed to get health:', err);\n return {\n cpu: { usage: 0 },\n memory: { usage: 0 },\n error: err.message\n };\n });\n },\n\n // Utilitaires\n formatBytes: function(bytes) {\n if (bytes === 0) return '0 B';\n var k = 1024;\n var sizes = ['B', 'KB', 'MB', 'GB'];\n var i = Math.floor(Math.log(bytes) / Math.log(k));\n return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];\n }\n});\n</code></pre>"},{"location":"development-guidelines/#view-template","title":"View Template","text":"<p>Fichier: <code>htdocs/luci-static/resources/view/<module-name>/overview.js</code></p> <pre><code>'use strict';\n'require view';\n'require ui';\n'require dom';\n'require poll';\n'require <module-name>/api as API';\n\nreturn view.extend({\n // State\n healthData: null,\n sysInfo: null,\n\n // Load data\n load: function() {\n return Promise.all([\n API.getStatus(),\n API.getHealth()\n ]);\n },\n\n // Render UI\n render: function(data) {\n var self = this;\n this.sysInfo = data[0] || {};\n this.healthData = data[1] || {};\n\n var container = E('div', { 'class': '<module>-dashboard' }, [\n // Link CSS files\n E('link', { 'rel': 'stylesheet', 'href': L.resource('<module>/common.css') }),\n E('link', { 'rel': 'stylesheet', 'href': L.resource('<module>/overview.css') }),\n\n // Header\n this.renderHeader(),\n\n // Content\n this.renderContent()\n ]);\n\n // Setup auto-refresh\n poll.add(L.bind(function() {\n return Promise.all([\n API.getStatus(),\n API.getHealth()\n ]).then(L.bind(function(refreshData) {\n this.sysInfo = refreshData[0] || {};\n this.healthData = refreshData[1] || {};\n this.updateDashboard();\n }, this));\n }, this), 30); // Refresh every 30s\n\n return container;\n },\n\n renderHeader: function() {\n return E('div', { 'class': 'sh-page-header' }, [\n // Header content\n ]);\n },\n\n renderContent: function() {\n return E('div', { 'class': 'sh-content' }, [\n // Main content\n ]);\n },\n\n updateDashboard: function() {\n // Update existing DOM elements\n var element = document.querySelector('.my-element');\n if (element) {\n dom.content(element, this.renderContent());\n }\n },\n\n // Required stubs for LuCI\n handleSaveApply: null,\n handleSave: null,\n handleReset: null\n});\n</code></pre>"},{"location":"development-guidelines/#event-handling-pattern","title":"Event Handling Pattern","text":"<pre><code>// \u2705 CORRECT: Bind events apr\u00e8s render\nrender: function(data) {\n var container = E('div', {}, [\n E('button', {\n 'id': 'my-button',\n 'class': 'sh-btn sh-btn-primary'\n }, 'Click Me')\n ]);\n\n // Ajouter l'\u00e9v\u00e9nement apr\u00e8s le container est cr\u00e9\u00e9\n container.addEventListener('click', function(ev) {\n if (ev.target && ev.target.id === 'my-button') {\n self.handleButtonClick();\n }\n });\n\n return container;\n},\n\nhandleButtonClick: function() {\n ui.addNotification(null, E('p', 'Button clicked!'), 'info');\n}\n</code></pre>"},{"location":"development-guidelines/#common-javascript-errors","title":"Common JavaScript Errors","text":""},{"location":"development-guidelines/#error-object-htmlbuttonelement-affiche","title":"Error: \"[object HTMLButtonElement]\" affich\u00e9","text":"<p>Cause: Array imbriqu\u00e9 quand E() attend un array simple</p> <pre><code>// \u274c INCORRECT\nE('div', {}, [\n this.renderButtons() // renderButtons retourne d\u00e9j\u00e0 un array\n])\n\n// \u2705 CORRECT\nE('div', {},\n this.renderButtons() // Pas de [ ] suppl\u00e9mentaire\n)\n</code></pre>"},{"location":"development-guidelines/#error-cannot-read-property-of-undefined","title":"Error: \"Cannot read property of undefined\"","text":"<p>Cause: Donn\u00e9es API non disponibles</p> <pre><code>// \u274c INCORRECT\nvar cpuUsage = this.healthData.cpu.usage;\n\n// \u2705 CORRECT (avec optional chaining)\nvar cpuUsage = (this.healthData.cpu && this.healthData.cpu.usage) || 0;\n// ou\nvar cpuUsage = this.healthData.cpu?.usage || 0; // ES2020\n</code></pre>"},{"location":"development-guidelines/#error-poll-callback-failed","title":"Error: \"poll callback failed\"","text":"<p>Cause: Promise non retourn\u00e9e dans poll.add</p> <pre><code>// \u274c INCORRECT\npoll.add(function() {\n API.getHealth(); // Pas de return!\n}, 30);\n\n// \u2705 CORRECT\npoll.add(function() {\n return API.getHealth().then(function(data) {\n // Update UI\n });\n}, 30);\n</code></pre>"},{"location":"development-guidelines/#cssstyling-standards","title":"CSS/Styling Standards","text":""},{"location":"development-guidelines/#file-organization","title":"File Organization","text":"<pre><code><module-name>/\n\u251c\u2500\u2500 common.css # Shared components (headers, buttons, cards, tabs)\n\u251c\u2500\u2500 overview.css # Overview page specific\n\u251c\u2500\u2500 services.css # Services page specific\n\u2514\u2500\u2500 *.css # Other page-specific styles\n</code></pre>"},{"location":"development-guidelines/#css-file-template","title":"CSS File Template","text":"<pre><code>/**\n * Module Name - Page/Component Styles\n * Description of what this file styles\n * Version: X.Y.Z\n */\n\n/* === Import shared styles (if needed) === */\n/* Not required if loaded in HTML */\n\n/* === Page-specific variables (if needed) === */\n:root {\n --page-specific-var: value;\n}\n\n/* === Layout === */\n.module-page-container {\n /* Layout styles */\n}\n\n/* === Components === */\n.module-component {\n /* Component styles */\n}\n\n/* === Responsive === */\n@media (max-width: 768px) {\n /* Mobile styles */\n}\n\n/* === Dark Mode Overrides === */\n[data-theme=\"dark\"] .module-component {\n /* Dark mode specific */\n}\n</code></pre>"},{"location":"development-guidelines/#css-best-practices","title":"CSS Best Practices","text":""},{"location":"development-guidelines/#1-toujours-utiliser-les-variables-css","title":"1. TOUJOURS utiliser les variables CSS","text":"<pre><code>/* \u274c INCORRECT */\n.my-card {\n background: #12121a;\n color: #fafafa;\n}\n\n/* \u2705 CORRECT */\n.my-card {\n background: var(--sh-bg-card);\n color: var(--sh-text-primary);\n}\n</code></pre>"},{"location":"development-guidelines/#2-prefix-classes-par-module","title":"2. Prefix classes par module","text":"<pre><code>/* System Hub */\n.sh-page-header { }\n.sh-card { }\n.sh-btn { }\n\n/* SecuBox */\n.sb-module-grid { }\n.sb-dashboard { }\n\n/* Module sp\u00e9cifique */\n.netdata-chart { }\n.crowdsec-alert { }\n</code></pre>"},{"location":"development-guidelines/#3-transitions-coherentes","title":"3. Transitions coh\u00e9rentes","text":"<pre><code>/* Standard transition */\ntransition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);\n\n/* Quick transition (hover states) */\ntransition: all 0.2s ease;\n\n/* Smooth transition (large movements) */\ntransition: all 0.5s ease;\n</code></pre>"},{"location":"development-guidelines/#4-responsive-breakpoints","title":"4. Responsive breakpoints","text":"<pre><code>/* Mobile */\n@media (max-width: 768px) {\n .sh-stats-grid {\n grid-template-columns: repeat(2, 1fr);\n }\n}\n\n/* Tablet */\n@media (min-width: 769px) and (max-width: 1024px) {\n /* Tablet specific */\n}\n\n/* Desktop */\n@media (min-width: 1025px) {\n /* Desktop specific */\n}\n</code></pre>"},{"location":"development-guidelines/#5-dark-mode-obligatoire","title":"5. Dark mode OBLIGATOIRE","text":"<p>Toujours fournir des styles dark mode:</p> <pre><code>/* Light mode (default) */\n.my-component {\n background: var(--sh-bg-card);\n border: 1px solid var(--sh-border);\n}\n\n/* Dark mode override */\n[data-theme=\"dark\"] .my-component {\n background: var(--sh-bg-card);\n border-color: var(--sh-border);\n}\n</code></pre>"},{"location":"development-guidelines/#z-index-scale","title":"Z-index Scale","text":"<p>Respecter cette \u00e9chelle:</p> <pre><code>--z-base: 0;\n--z-dropdown: 100;\n--z-sticky: 200;\n--z-fixed: 300;\n--z-modal-backdrop: 400;\n--z-modal: 500;\n--z-popover: 600;\n--z-tooltip: 700;\n</code></pre>"},{"location":"development-guidelines/#common-errors-solutions","title":"Common Errors & Solutions","text":""},{"location":"development-guidelines/#1-rpcd-object-not-found-32000","title":"1. RPCD Object Not Found (-32000)","text":"<p>Erreur compl\u00e8te: <pre><code>RPC call to luci.system-hub/getHealth failed with error -32000: Object not found\n</code></pre></p> <p>Diagnostic: <pre><code># 1. V\u00e9rifier que le fichier RPCD existe\nls -la /usr/libexec/rpcd/luci.system-hub\n\n# 2. V\u00e9rifier qu'il est ex\u00e9cutable\nchmod +x /usr/libexec/rpcd/luci.system-hub\n\n# 3. Lister les objets ubus\nubus list | grep system-hub\n\n# 4. Si absent, red\u00e9marrer RPCD\n/etc/init.d/rpcd restart\nubus list | grep system-hub\n</code></pre></p> <p>Solutions: 1. Renommer le fichier RPCD pour correspondre exactement 2. V\u00e9rifier permissions (755 ou rwxr-xr-x) 3. Red\u00e9marrer rpcd</p>"},{"location":"development-guidelines/#2-view-not-found-404","title":"2. View Not Found (404)","text":"<p>Erreur: <pre><code>HTTP error 404 while loading class file '/luci-static/resources/view/system-hub/overview.js'\n</code></pre></p> <p>Diagnostic: <pre><code># 1. V\u00e9rifier que le fichier existe\nls -la /www/luci-static/resources/view/system-hub/overview.js\n\n# 2. V\u00e9rifier le chemin dans menu.d\ngrep \"path\" /usr/share/luci/menu.d/luci-app-system-hub.json\n</code></pre></p> <p>Solutions: 1. V\u00e9rifier que le path dans menu JSON correspond au fichier 2. V\u00e9rifier permissions du fichier (644) 3. Nettoyer cache: <code>rm -f /tmp/luci-indexcache /tmp/luci-modulecache/*</code></p>"},{"location":"development-guidelines/#3-css-not-loading-403-forbidden","title":"3. CSS Not Loading (403 Forbidden)","text":"<p>Erreur: <pre><code>GET /luci-static/resources/system-hub/common.css 403 Forbidden\n</code></pre></p> <p>Diagnostic: <pre><code># V\u00e9rifier permissions\nls -la /www/luci-static/resources/system-hub/common.css\n</code></pre></p> <p>Solution: <pre><code># Corriger permissions\nchmod 644 /www/luci-static/resources/system-hub/*.css\n</code></pre></p>"},{"location":"development-guidelines/#4-invalid-json-from-rpcd","title":"4. Invalid JSON from RPCD","text":"<p>Erreur dans browser console: <pre><code>SyntaxError: Unexpected token in JSON at position X\n</code></pre></p> <p>Diagnostic: <pre><code># Tester le JSON directement\n/usr/libexec/rpcd/luci.system-hub call getHealth | jsonlint\n\n# Ou avec jq\n/usr/libexec/rpcd/luci.system-hub call getHealth | jq .\n</code></pre></p> <p>Solutions courantes: <pre><code># \u274c INCORRECT - Quote simple non \u00e9chapp\u00e9e\necho '{\"error\": \"can't process\"}'\n\n# \u2705 CORRECT - Utiliser printf et doubles quotes\nprintf '{\"error\": \"cannot process\"}\\n'\n\n# \u274c INCORRECT - Variable non quot\u00e9e\necho \"{\\\"value\\\": $var}\"\n\n# \u2705 CORRECT - Variable quot\u00e9e\nprintf '{\"value\": \"%s\"}\\n' \"$var\"\n</code></pre></p>"},{"location":"development-guidelines/#5-browser-cache-issues","title":"5. Browser Cache Issues","text":"<p>Sympt\u00f4mes: - Changements CSS/JS non visibles - Anciennes donn\u00e9es affich\u00e9es - Code mis \u00e0 jour mais interface identique</p> <p>Solutions: <pre><code># 1. C\u00f4t\u00e9 serveur - nettoyer cache LuCI\nssh root@router \"rm -f /tmp/luci-indexcache /tmp/luci-modulecache/* && /etc/init.d/uhttpd restart\"\n\n# 2. C\u00f4t\u00e9 client - hard refresh\nCtrl + Shift + R (Chrome/Firefox)\nCtrl + F5 (Windows)\nCmd + Shift + R (Mac)\n\n# 3. Mode priv\u00e9/incognito pour test\nCtrl + Shift + N (Chrome)\nCtrl + Shift + P (Firefox)\n</code></pre></p>"},{"location":"development-guidelines/#6-acl-access-denied","title":"6. ACL Access Denied","text":"<p>Erreur: <pre><code>Access to path '/admin/secubox/system/system-hub' denied\n</code></pre></p> <p>Diagnostic: <pre><code># V\u00e9rifier ACL\ncat /usr/share/rpcd/acl.d/luci-app-system-hub.json | jq .\n\n# V\u00e9rifier que m\u00e9thodes ubus sont list\u00e9es\ngrep \"getHealth\" /usr/share/rpcd/acl.d/luci-app-system-hub.json\n</code></pre></p> <p>Solution: Ajouter la m\u00e9thode manquante dans ACL et red\u00e9marrer rpcd.</p>"},{"location":"development-guidelines/#validation-checklist","title":"Validation Checklist","text":""},{"location":"development-guidelines/#pre-commit-checklist","title":"Pre-Commit Checklist","text":"<p>Avant chaque commit, v\u00e9rifier:</p> <ul> <li> RPCD Script:</li> <li> Nom fichier correspond \u00e0 objet ubus</li> <li> Ex\u00e9cutable (chmod +x)</li> <li> Structure list/call correcte</li> <li> Retourne JSON valide</li> <li> <p> Toutes m\u00e9thodes impl\u00e9ment\u00e9es</p> </li> <li> <p> Menu & ACL:</p> </li> <li> Path menu correspond au fichier vue</li> <li> ACL liste toutes les m\u00e9thodes ubus</li> <li> <p> JSON valide (jsonlint)</p> </li> <li> <p> JavaScript:</p> </li> <li> 'use strict' en premi\u00e8re ligne</li> <li> Imports requis pr\u00e9sents</li> <li> Pas de console.log en prod</li> <li> Gestion d'erreur sur API calls</li> <li> <p> Event handlers bind\u00e9s correctement</p> </li> <li> <p> CSS:</p> </li> <li> Variables CSS utilis\u00e9es (pas de hardcode)</li> <li> Classes prefix\u00e9es (sh-, sb-, module-)</li> <li> Dark mode support\u00e9</li> <li> Responsive (max-width: 768px)</li> <li> <p> Transitions coh\u00e9rentes</p> </li> <li> <p> Makefile:</p> </li> <li> PKG_VERSION incr\u00e9ment\u00e9</li> <li> LUCI_DEPENDS correct</li> <li> Include path correct (../../luci.mk)</li> </ul>"},{"location":"development-guidelines/#pre-deploy-checklist","title":"Pre-Deploy Checklist","text":"<p>Avant d\u00e9ploiement sur routeur:</p> <ul> <li> <p> Validation scripts: <pre><code>./secubox-tools/validate-modules.sh\n</code></pre></p> </li> <li> <p> Test RPCD local: <pre><code>/usr/libexec/rpcd/luci.module-name list\n/usr/libexec/rpcd/luci.module-name call getStatus\n</code></pre></p> </li> <li> <p> Test JSON: <pre><code>find . -name \"*.json\" -exec jsonlint {} \\;\n</code></pre></p> </li> <li> <p> Shellcheck: <pre><code>shellcheck root/usr/libexec/rpcd/*\n</code></pre></p> </li> <li> <p> Permissions: <pre><code># RPCD scripts\nchmod 755 root/usr/libexec/rpcd/*\n\n# CSS/JS files\nchmod 644 htdocs/luci-static/resources/**/*\n</code></pre></p> </li> </ul>"},{"location":"development-guidelines/#post-deploy-checklist","title":"Post-Deploy Checklist","text":"<p>Apr\u00e8s d\u00e9ploiement:</p> <ul> <li> <p> Services: <pre><code>/etc/init.d/rpcd status\n/etc/init.d/uhttpd status\n</code></pre></p> </li> <li> <p> ubus objects: <pre><code>ubus list | grep luci.module-name\n</code></pre></p> </li> <li> <p> Fichiers pr\u00e9sents: <pre><code>ls -la /www/luci-static/resources/view/module-name/\nls -la /www/luci-static/resources/module-name/\n</code></pre></p> </li> <li> <p> Permissions correctes: <pre><code>ls -la /usr/libexec/rpcd/luci.module-name\nls -la /www/luci-static/resources/module-name/*.css\n</code></pre></p> </li> <li> <p> Test navigateur:</p> </li> <li> Ouvrir en mode priv\u00e9</li> <li> V\u00e9rifier console (F12) - pas d'erreurs</li> <li> V\u00e9rifier Network tab - tous les fichiers chargent (200)</li> <li> Tester dark/light mode</li> <li> Tester responsive (mobile view)</li> </ul>"},{"location":"development-guidelines/#deployment-procedures","title":"Deployment Procedures","text":""},{"location":"development-guidelines/#deployment-workflow","title":"Deployment Workflow","text":"<p>The following flowchart illustrates the complete deployment process with validation checkpoints:</p> <pre><code>flowchart TD\n START([Start Deployment]) --> LOCAL_VAL{Local Validation<br/>Passed?}\n LOCAL_VAL -->|No| FIX_LOCAL[Fix Issues Locally]\n FIX_LOCAL --> LOCAL_VAL\n LOCAL_VAL -->|Yes| CHECK_DISK{Disk Space<br/>< 90%?}\n\n CHECK_DISK -->|No| CLEAN_DISK[Clean Temp Files<br/>& Old Backups]\n CLEAN_DISK --> CHECK_DISK\n CHECK_DISK -->|Yes| FIX_PERM_LOCAL[Fix Permissions<br/>Local Source]\n\n FIX_PERM_LOCAL --> COPY[Copy Files to Router<br/>scp JS/CSS/RPCD]\n COPY --> FIX_PERM_REMOTE[Fix Permissions<br/>Remote Files<br/>755 RPCD / 644 CSS-JS]\n FIX_PERM_REMOTE --> CLEAR[Clear LuCI Cache<br/>/tmp/luci-*]\n CLEAR --> RESTART[Restart Services<br/>rpcd + uhttpd]\n\n RESTART --> V1{ubus Object<br/>Available?}\n V1 -->|No| DEBUG1[Debug RPCD Script<br/>Check naming & permissions]\n DEBUG1 --> FIX_PERM_REMOTE\n\n V1 -->|Yes| V2{Files<br/>Accessible?}\n V2 -->|403 Error| DEBUG2[Fix File Permissions<br/>chmod 644]\n DEBUG2 --> FIX_PERM_REMOTE\n\n V2 -->|Yes| V3{Menu Path<br/>Matches View?}\n V3 -->|404 Error| DEBUG3[Fix Menu JSON Path]\n DEBUG3 --> COPY\n\n V3 -->|Yes| V4{UI Loads<br/>Correctly?}\n V4 -->|Errors| DEBUG4[Check Browser Console<br/>Fix JavaScript Errors]\n DEBUG4 --> COPY\n\n V4 -->|Yes| TEST[Browser Testing<br/>Private Mode<br/>Dark/Light Mode<br/>Responsive]\n TEST --> SUCCESS([\u2705 Deployment Success])\n\n style START fill:#6366f1,color:#fff,stroke:#4f46e5\n style SUCCESS fill:#22c55e,color:#fff,stroke:#16a34a\n style DEBUG1 fill:#ef4444,color:#fff,stroke:#dc2626\n style DEBUG2 fill:#ef4444,color:#fff,stroke:#dc2626\n style DEBUG3 fill:#ef4444,color:#fff,stroke:#dc2626\n style DEBUG4 fill:#ef4444,color:#fff,stroke:#dc2626\n style CHECK_DISK fill:#f59e0b,color:#fff,stroke:#d97706\n style LOCAL_VAL fill:#8b5cf6,color:#fff,stroke:#7c3aed</code></pre> <p>Deployment Stages: 1. Local Validation: Run <code>validate-modules.sh</code> and <code>fix-permissions.sh --local</code> 2. Pre-Flight Checks: Disk space and permission verification 3. File Transfer: Copy JavaScript, CSS, and RPCD scripts 4. Remote Setup: Fix permissions and clear caches 5. Service Restart: Reload rpcd and uhttpd daemons 6. Validation: Multi-stage verification (ubus, files, menu, UI) 7. Testing: Browser testing in private mode</p> <p>Common Error Recovery Paths: - Object not found (-32000): Check RPCD script naming and permissions - 403 Forbidden: Fix file permissions to 644 for CSS/JS - 404 Not Found: Verify menu path matches view file location - JavaScript errors: Check browser console and fix code issues</p>"},{"location":"development-guidelines/#pre-deployment-checks-critical","title":"\u26a0\ufe0f Pre-Deployment Checks (CRITICAL)","text":"<p>TOUJOURS ex\u00e9cuter ces v\u00e9rifications AVANT tout d\u00e9ploiement:</p>"},{"location":"development-guidelines/#1-verification-de-lespace-disque","title":"1. V\u00e9rification de l'Espace Disque","text":"<pre><code># Sur le routeur cible\nssh root@192.168.8.191 \"df -h | grep overlay\"\n\n# V\u00e9rifier que l'utilisation est < 90%\n# Exemple OK:\n# /dev/loop0 98.8M 45.2M 53.6M 46% /overlay\n\n# Exemple CRITIQUE (STOP deployment):\n# /dev/loop0 98.8M 98.8M 0 100% /overlay \u2190 PLEIN!\n</code></pre> <p>Si l'overlay est plein (\u226595%): <pre><code># Lib\u00e9rer de l'espace avant d\u00e9ploiement\nssh root@192.168.8.191 << 'EOF'\n# Supprimer fichiers temporaires\nrm -rf /tmp/*.ipk /tmp/luci-* 2>/dev/null\n\n# Supprimer anciens backups (>7 jours)\nfind /root -name '*.backup-*' -type f -mtime +7 -delete 2>/dev/null\n\n# V\u00e9rifier packages inutilis\u00e9s\nopkg list-installed | grep -E 'netdata|unused'\n\n# Apr\u00e8s nettoyage, v\u00e9rifier l'espace lib\u00e9r\u00e9\ndf -h | grep overlay\nEOF\n</code></pre></p> <p>Tailles typiques \u00e0 surveiller: - Netdata web UI: ~22MB (consid\u00e9rer suppression si non utilis\u00e9) - Modules LuCI: ~1-2MB chacun - Fichiers CSS/JS: ~10-50KB chacun</p>"},{"location":"development-guidelines/#2-verification-des-permissions-critique-pour-eviter-erreurs-403","title":"2. V\u00e9rification des Permissions (Critique pour \u00c9viter Erreurs 403)","text":"<p>Permissions OBLIGATOIRES:</p> Type Permission Octal Raison RPCD scripts <code>rwxr-xr-x</code> <code>755</code> Ex\u00e9cutable par system CSS files <code>rw-r--r--</code> <code>644</code> Lecture web server JS files <code>rw-r--r--</code> <code>644</code> Lecture web server JSON files <code>rw-r--r--</code> <code>644</code> Lecture rpcd <p>Erreur commune: Fichiers cr\u00e9\u00e9s avec <code>600</code> (rw-------) au lieu de <code>644</code></p> <p>Sympt\u00f4me: HTTP 403 Forbidden lors du chargement de fichiers JS/CSS</p> <p>Exemple d'erreur: <pre><code>NetworkError: HTTP error 403 while loading class file\n\"/luci-static/resources/view/netdata-dashboard/dashboard.js\"\n</code></pre></p> <p>Diagnostic rapide: <pre><code># V\u00e9rifier permissions des fichiers d\u00e9ploy\u00e9s\nssh root@192.168.8.191 \"ls -la /www/luci-static/resources/view/MODULE_NAME/\"\n\n# Chercher fichiers avec permissions incorrectes (600)\nssh root@192.168.8.191 \"find /www/luci-static/resources/view/ -type f -name '*.js' -perm 600\"\n\n# MAUVAIS (cause 403):\n# -rw------- 1 root root 9763 dashboard.js \u2190 600 = pas lisible par web!\n\n# BON:\n# -rw-r--r-- 1 root root 9763 dashboard.js \u2190 644 = OK\n</code></pre></p> <p>Correction imm\u00e9diate: <pre><code># Corriger TOUS les fichiers CSS/JS\nssh root@192.168.8.191 << 'EOF'\nfind /www/luci-static/resources/ -name '*.css' -exec chmod 644 {} \\;\nfind /www/luci-static/resources/ -name '*.js' -exec chmod 644 {} \\;\nfind /usr/libexec/rpcd/ -name 'luci.*' -exec chmod 755 {} \\;\nEOF\n</code></pre></p> <p>\u26a1 Correction Automatique (Recommand\u00e9):</p> <p>Utiliser le script automatique qui v\u00e9rifie et corrige toutes les permissions:</p> <pre><code># Corriger permissions locales (source code)\n./secubox-tools/fix-permissions.sh --local\n\n# Corriger permissions sur routeur\n./secubox-tools/fix-permissions.sh --remote\n\n# Corriger les deux (local + remote)\n./secubox-tools/fix-permissions.sh\n</code></pre> <p>Le script <code>fix-permissions.sh</code> effectue automatiquement: - \u2705 Fixe tous les RPCD scripts \u00e0 755 - \u2705 Fixe tous les CSS \u00e0 644 - \u2705 Fixe tous les JS \u00e0 644 - \u2705 V\u00e9rifie qu'aucun fichier 600 ne reste - \u2705 Clear cache et restart services (remote mode) - \u2705 Affiche un rapport complet des changements</p> <p>\ud83d\udd0d Validation Automatique des Permissions:</p> <p>Le script <code>validate-modules.sh</code> inclut maintenant un Check 7 qui v\u00e9rifie automatiquement les permissions:</p> <pre><code>./secubox-tools/validate-modules.sh\n\n# Check 7 validera:\n# \u2713 Tous les RPCD sont 755\n# \u2713 Tous les CSS sont 644\n# \u2713 Tous les JS sont 644\n# \u274c Affichera erreurs si permissions incorrectes\n</code></pre> <p>Workflow recommand\u00e9: 1. D\u00e9velopper/modifier code 2. <code>./secubox-tools/fix-permissions.sh --local</code> (avant commit) 3. <code>./secubox-tools/validate-modules.sh</code> (v\u00e9rifier tout) 4. Commit & push 5. Deploy sur routeur 6. <code>./secubox-tools/fix-permissions.sh --remote</code> (apr\u00e8s deploy)</p>"},{"location":"development-guidelines/#3-post-deployment-verification","title":"3. Post-Deployment Verification","text":"<p>Checklist apr\u00e8s d\u00e9ploiement:</p> <pre><code>#!/bin/bash\nROUTER=\"root@192.168.8.191\"\nMODULE=\"module-name\"\n\necho \"\ud83d\udd0d Post-Deployment Verification\"\necho \"\"\n\n# 1. V\u00e9rifier espace disque\necho \"1. Espace disque restant:\"\nssh \"$ROUTER\" \"df -h | grep overlay | awk '{print \\$5}'\" || echo \"\u274c FAIL\"\n\n# 2. V\u00e9rifier permissions CSS/JS\necho \"2. Permissions CSS/JS:\"\nssh \"$ROUTER\" \"find /www/luci-static/resources/$MODULE -type f \\( -name '*.css' -o -name '*.js' \\) ! -perm 644\" | \\\n if [ -z \"$(cat)\" ]; then echo \"\u2705 OK\"; else echo \"\u274c FAIL - Permissions incorrectes\"; fi\n\n# 3. V\u00e9rifier permissions RPCD\necho \"3. Permissions RPCD:\"\nssh \"$ROUTER\" \"ls -l /usr/libexec/rpcd/luci.$MODULE | grep -q rwxr-xr-x\" && echo \"\u2705 OK\" || echo \"\u274c FAIL\"\n\n# 4. V\u00e9rifier ubus object\necho \"4. ubus object disponible:\"\nssh \"$ROUTER\" \"ubus list | grep -q luci.$MODULE\" && echo \"\u2705 OK\" || echo \"\u274c FAIL\"\n\n# 5. V\u00e9rifier fichiers accessibles (HTTP)\necho \"5. Fichiers web accessibles:\"\nssh \"$ROUTER\" \"test -r /www/luci-static/resources/$MODULE/common.css\" && echo \"\u2705 OK\" || echo \"\u26a0\ufe0f common.css non trouv\u00e9\"\n\n# 6. V\u00e9rifier cache cleared\necho \"6. Cache LuCI cleared:\"\nssh \"$ROUTER\" \"test ! -f /tmp/luci-indexcache\" && echo \"\u2705 OK\" || echo \"\u26a0\ufe0f Cache encore pr\u00e9sent\"\n\necho \"\"\necho \"\u2705 V\u00e9rification termin\u00e9e\"\n</code></pre>"},{"location":"development-guidelines/#4-common-deployment-errors","title":"4. Common Deployment Errors","text":"Erreur Cause Solution Rapide HTTP 403 Forbidden Permissions 600 au lieu de 644 <code>chmod 644 *.js *.css</code> No space left on device Overlay plein Nettoyer /tmp, supprimer anciens backups Object not found -32000 RPCD pas ex\u00e9cutable ou mal nomm\u00e9 <code>chmod 755 rpcd/luci.*</code> + v\u00e9rifier nom Module not appearing Cache LuCI pas cleared <code>rm /tmp/luci-*</code> + restart services Changes not visible Cache navigateur Mode priv\u00e9 + Ctrl+Shift+R"},{"location":"development-guidelines/#5-emergency-disk-space-recovery","title":"5. Emergency Disk Space Recovery","text":"<p>Si le d\u00e9ploiement \u00e9choue avec \"No space left on device\":</p> <pre><code>#!/bin/bash\nROUTER=\"root@192.168.8.191\"\n\necho \"\ud83d\udea8 Emergency Disk Space Recovery\"\necho \"\"\n\n# 1. Analyser l'utilisation\necho \"Top 10 consumers:\"\nssh \"$ROUTER\" \"du -k /overlay/upper 2>/dev/null | sort -rn | head -10\"\n\n# 2. Nettoyer temporaires\necho \"\"\necho \"Cleaning temp files...\"\nssh \"$ROUTER\" \"rm -rf /tmp/*.ipk /tmp/luci-* /root/*.ipk 2>/dev/null\"\n\n# 3. Supprimer anciens backups\necho \"Removing old backups (>7 days)...\"\nssh \"$ROUTER\" \"find /root -name '*.backup-*' -mtime +7 -delete 2>/dev/null\"\n\n# 4. Option: Supprimer Netdata Web UI (lib\u00e8re ~22MB)\necho \"\"\necho \"\u26a0\ufe0f Option: Remove Netdata Web UI (saves ~22MB)?\"\nread -p \"Continue? (y/N) \" -n 1 -r\nif [[ $REPLY =~ ^[Yy]$ ]]; then\n ssh \"$ROUTER\" \"opkg remove netdata-web 2>/dev/null || rm -rf /usr/share/netdata/web/*\"\nfi\n\n# 5. V\u00e9rifier espace lib\u00e9r\u00e9\necho \"\"\necho \"Space after cleanup:\"\nssh \"$ROUTER\" \"df -h | grep overlay\"\n</code></pre>"},{"location":"development-guidelines/#standard-deployment-script-template","title":"Standard Deployment Script Template","text":"<pre><code>#!/bin/bash\n# Deploy <Module Name>\n\nROUTER=\"root@192.168.8.191\"\nMODULE=\"<module-name>\"\nLOCAL_DIR=\"/path/to/luci-app-$MODULE/htdocs/luci-static/resources\"\nREMOTE_DIR=\"/www/luci-static/resources\"\n\necho \"\ud83d\udce6 D\u00e9ploiement $MODULE\"\necho \"\"\n\n# 1. Deploy JS files\necho \"1. Copie des fichiers JS...\"\nscp \"$LOCAL_DIR/view/$MODULE/\"*.js \"$ROUTER:$REMOTE_DIR/view/$MODULE/\"\nscp \"$LOCAL_DIR/$MODULE/api.js\" \"$ROUTER:$REMOTE_DIR/$MODULE/\"\n\n# 2. Deploy CSS files\necho \"2. Copie des fichiers CSS...\"\nscp \"$LOCAL_DIR/$MODULE/\"*.css \"$ROUTER:$REMOTE_DIR/$MODULE/\"\n\n# 3. Deploy RPCD backend\necho \"3. Copie du backend RPCD...\"\nscp \"root/usr/libexec/rpcd/luci.$MODULE\" \"$ROUTER:/usr/libexec/rpcd/\"\n\n# 4. Fix permissions\necho \"4. Correction des permissions...\"\nssh \"$ROUTER\" \"chmod 755 /usr/libexec/rpcd/luci.$MODULE\"\nssh \"$ROUTER\" \"chmod 644 $REMOTE_DIR/$MODULE/*.css\"\nssh \"$ROUTER\" \"chmod 644 $REMOTE_DIR/view/$MODULE/*.js\"\n\n# 5. Clear cache\necho \"5. Nettoyage du cache...\"\nssh \"$ROUTER\" \"rm -f /tmp/luci-indexcache /tmp/luci-modulecache/* 2>/dev/null\"\n\n# 6. Restart services\necho \"6. Red\u00e9marrage des services...\"\nssh \"$ROUTER\" \"/etc/init.d/rpcd restart\"\nssh \"$ROUTER\" \"/etc/init.d/uhttpd restart\"\n\n# 7. Verify\necho \"\"\necho \"7. V\u00e9rification...\"\nssh \"$ROUTER\" \"ubus list | grep luci.$MODULE\"\n\necho \"\"\necho \"\u2705 D\u00e9ploiement termin\u00e9!\"\necho \"\"\necho \"\ud83c\udf10 Testez (mode priv\u00e9):\"\necho \" https://192.168.8.191/cgi-bin/luci/admin/secubox/path/to/$MODULE\"\n</code></pre>"},{"location":"development-guidelines/#rollback-procedure","title":"Rollback Procedure","text":"<p>En cas de probl\u00e8me:</p> <pre><code>#!/bin/bash\n# Rollback to previous version\n\nROUTER=\"root@192.168.8.191\"\nBACKUP_DIR=\"/root/luci-backups/$(date +%Y%m%d)\"\n\n# 1. Cr\u00e9er backup avant deploy\nssh \"$ROUTER\" \"mkdir -p $BACKUP_DIR\"\nssh \"$ROUTER\" \"cp -r /www/luci-static/resources/module-name $BACKUP_DIR/\"\nssh \"$ROUTER\" \"cp /usr/libexec/rpcd/luci.module-name $BACKUP_DIR/\"\n\n# 2. En cas de probl\u00e8me, restore\nssh \"$ROUTER\" \"cp -r $BACKUP_DIR/module-name /www/luci-static/resources/\"\nssh \"$ROUTER\" \"cp $BACKUP_DIR/luci.module-name /usr/libexec/rpcd/\"\nssh \"$ROUTER\" \"/etc/init.d/rpcd restart && /etc/init.d/uhttpd restart\"\n</code></pre>"},{"location":"development-guidelines/#version-control","title":"Version Control","text":"<p>Toujours incr\u00e9menter les versions:</p> <pre><code># Makefile\nPKG_VERSION:=0.3.0\nPKG_RELEASE:=1\n</code></pre> <pre><code>/* CSS files */\n/**\n * Module - Styles\n * Version: 0.3.0\n */\n</code></pre> <pre><code>// JavaScript\n// Version: 0.3.0\n</code></pre> <p>Semantic Versioning: - MAJOR.MINOR.PATCH (1.2.3) - MAJOR: Breaking changes - MINOR: New features (backward compatible) - PATCH: Bug fixes</p>"},{"location":"development-guidelines/#quick-reference","title":"Quick Reference","text":""},{"location":"development-guidelines/#essential-commands","title":"Essential Commands","text":"<pre><code># Validation\n./secubox-tools/validate-modules.sh\n\n# Build (local)\n./secubox-tools/local-build.sh build luci-app-module-name\n\n# Deploy files\nscp file.js root@router:/www/luci-static/resources/\n\n# Fix permissions\nssh root@router \"chmod 644 /www/luci-static/resources/**/*.css\"\nssh root@router \"chmod 755 /usr/libexec/rpcd/luci.*\"\n\n# Clear cache\nssh root@router \"rm -f /tmp/luci-indexcache /tmp/luci-modulecache/*\"\n\n# Restart services\nssh root@router \"/etc/init.d/rpcd restart && /etc/init.d/uhttpd restart\"\n\n# Test ubus\nssh root@router \"ubus list | grep luci\"\nssh root@router \"ubus call luci.module-name getStatus\"\n\n# Validate JSON\njsonlint file.json\njq . file.json\n</code></pre>"},{"location":"development-guidelines/#css-classes-quick-reference","title":"CSS Classes Quick Reference","text":"<pre><code>/* Layout */\n.sh-page-header /* Page header container */\n.sh-page-title /* Page title (gradient text) */\n.sh-page-subtitle /* Page subtitle */\n\n/* Stats */\n.sh-stats-grid /* Grid for stat badges (130px min) */\n.sh-stat-badge /* Stat badge container */\n.sh-stat-value /* Stat value (monospace) */\n.sh-stat-label /* Stat label (uppercase) */\n\n/* Cards */\n.sh-card /* Card container (with gradient border on hover) */\n.sh-card-success /* Card with green border */\n.sh-card-danger /* Card with red border */\n.sh-card-warning /* Card with orange border */\n.sh-card-header /* Card header */\n.sh-card-title /* Card title */\n.sh-card-body /* Card content */\n\n/* Buttons */\n.sh-btn /* Base button */\n.sh-btn-primary /* Primary button (gradient) */\n.sh-btn-success /* Success button (green) */\n.sh-btn-danger /* Danger button (red) */\n.sh-btn-secondary /* Secondary button (outline) */\n\n/* Tabs */\n.sh-filter-tabs /* Filter tabs container */\n.sh-filter-tab /* Filter tab */\n.sh-filter-tab.active /* Active filter tab (gradient) */\n.sh-nav-tabs /* Navigation tabs (sticky) */\n.sh-nav-tab /* Navigation tab */\n.sh-nav-tab.active /* Active nav tab (underline) */\n\n/* Utilities */\n.sh-gradient-text /* Gradient text effect */\n.sh-id-display /* Monospace ID display */\n.sh-empty-state /* Empty state placeholder */\n</code></pre>"},{"location":"development-guidelines/#color-variables-quick-reference","title":"Color Variables Quick Reference","text":"<pre><code>/* Text */\nvar(--sh-text-primary) /* Main text */\nvar(--sh-text-secondary) /* Secondary text */\n\n/* Backgrounds */\nvar(--sh-bg-primary) /* Main background */\nvar(--sh-bg-secondary) /* Secondary background */\nvar(--sh-bg-tertiary) /* Tertiary background */\nvar(--sh-bg-card) /* Card background */\n\n/* Borders */\nvar(--sh-border) /* Border color */\n\n/* Colors */\nvar(--sh-primary) /* Indigo #6366f1 */\nvar(--sh-primary-end) /* Violet #8b5cf6 */\nvar(--sh-success) /* Green #22c55e */\nvar(--sh-danger) /* Red #ef4444 */\nvar(--sh-warning) /* Orange #f59e0b */\n\n/* Effects */\nvar(--sh-shadow) /* Box shadow */\nvar(--sh-hover-shadow) /* Hover shadow */\nvar(--sh-hover-bg) /* Hover background */\n</code></pre>"},{"location":"development-guidelines/#ai-assistant-context-files","title":"AI Assistant Context Files","text":"<p>SecuBox work is shared between Claude and Codex assistants. Keep the context folders synchronized so any agent can resume work quickly:</p> Directory File Usage <code>.claude/</code> <code>HISTORY.md</code> Chronological log of UI/theme changes and major deployments <code>.claude/</code> <code>TODO.md</code> High-level backlog (UX polish, docs, automation ideas) <code>.claude/</code> <code>WIP.md</code> Active tasks, risks, and immediate next steps <code>.codex/</code> <code>HISTORY.md</code> Mirrors the development timeline for Codex sessions <code>.codex/</code> <code>TODO.md</code> Tooling-focused tasks (linting, scripts, build automation) <code>.codex/</code> <code>WIP.md</code> Status tracker for ongoing Codex efforts <p>Maintenance rules</p> <ol> <li>Update after each session: When finishing work, append a short bullet to HISTORY and adjust WIP/TODO so they reflect the new state.</li> <li>Reference deployment scripts: Note which <code>secubox-tools/*.sh</code> script was used (dashboard vs. full deploy) so the next assistant knows how to reproduce it.</li> <li>Keep entries concise: A single paragraph or bullet per update is enough; detailed specs remain in DOCS.</li> <li>Cross-check before big changes: Read both folders before starting work to avoid conflicts or duplicate efforts.</li> </ol> <p>Treat these files as living handoff notes\u2014if they drift, onboarding a new AI/teammate becomes significantly slower.</p>"},{"location":"development-guidelines/#conclusion","title":"Conclusion","text":"<p>Ce guide doit \u00eatre consult\u00e9 AVANT de: 1. Cr\u00e9er un nouveau module 2. Modifier des styles existants 3. Ajouter des m\u00e9thodes RPCD 4. D\u00e9ployer sur un routeur 5. D\u00e9bugger des erreurs</p> <p>En cas de doute, TOUJOURS: 1. Consulter ce guide 2. Ex\u00e9cuter validate-modules.sh 3. Tester en mode priv\u00e9 4. V\u00e9rifier la console browser (F12)</p> <p>Ressources suppl\u00e9mentaires: - CLAUDE.md - Architecture et build - secubox-tools/validate-modules.sh - Validation automatique - Templates/ - Templates de code</p> <p>Derni\u00e8re mise \u00e0 jour: 2025-12-26 Maintenu par: CyberMind Studio Version du guide: 1.0.0</p>"},{"location":"documentation-index/","title":"SecuBox Documentation Index","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active Complete Documentation for SecuBox OpenWrt Project</p>"},{"location":"documentation-index/#documentation-overview","title":"\ud83d\udcd6 Documentation Overview","text":"<p>This index provides quick access to all SecuBox documentation. Choose the document that matches your needs:</p>"},{"location":"documentation-index/#version-status-policy","title":"\ud83d\udcc5 Version & Status Policy","text":"<p>Every Markdown document in SecuBox must begin with metadata so contributors instantly see freshness:</p> <ul> <li>Include <code>Version</code>, <code>Last Updated</code> (YYYY-MM-DD), and <code>Status</code> (Active | Draft | Archived).</li> <li>New or regenerated docs start at <code>Version 1.0.0</code>; bump minor/patch numbers for incremental updates, major for structural rewrites.</li> <li>When editing any doc, update the <code>Last Updated</code> date and keep statuses in sync with the archive plan outlined in <code>TODO-ANALYSE.md</code>.</li> </ul> <p>Follow this template when creating or revising documentation:</p> <pre><code># Title\n\n**Version:** 1.0.0\n**Last Updated:** 2025-12-28\n**Status:** Active\n</code></pre>"},{"location":"documentation-index/#getting-started","title":"\ud83d\ude80 Getting Started","text":""},{"location":"documentation-index/#for-new-contributors","title":"For New Contributors","text":"<ol> <li>Start with QUICK-START.md - Essential rules and commands</li> <li>Read DEVELOPMENT-GUIDELINES.md - Complete development guide</li> <li>Review CLAUDE.md - Build system and architecture</li> </ol>"},{"location":"documentation-index/#for-ai-assisted-development","title":"For AI-Assisted Development","text":"<ol> <li>Use MODULE-IMPLEMENTATION-GUIDE.md - Step-by-step workflow</li> <li>Copy prompts from FEATURE-REGENERATION-PROMPTS.md</li> <li>Reference CODE-TEMPLATES.md for implementation patterns</li> </ol>"},{"location":"documentation-index/#for-existing-module-modification","title":"For Existing Module Modification","text":"<ol> <li>Check QUICK-START.md - Quick fixes and common commands</li> <li>Run validation: <code>./secubox-tools/validate-modules.sh</code></li> <li>Review DEVELOPMENT-GUIDELINES.md for specific topics</li> </ol>"},{"location":"documentation-index/#document-descriptions","title":"\ud83d\udcda Document Descriptions","text":""},{"location":"documentation-index/#1-quick-reference-documents","title":"1. Quick Reference Documents","text":""},{"location":"documentation-index/#quick-startmd","title":"QUICK-START.md \u26a1","text":"<p>Quick reference for common tasks - Read this first!</p> <p>Contents: - Critical naming rules (RPCD, menu paths, permissions) - Design system essentials (colors, fonts, CSS classes) - Common commands (validation, build, deploy, debug) - Quick code templates (RPCD, View, Headers, Cards) - Error quick fixes</p> <p>When to use: Daily development, quick lookups, debugging</p>"},{"location":"documentation-index/#codexmd","title":"CODEX.md \ud83e\udd16","text":"<p>Field manual for Codex/automation agents</p> <p>Contents: - Repository context and document map - Non-negotiable build/design standards - Prompt template for LLM workflows - Help & troubleshooting pointers - Documentation TODO radar and history</p> <p>When to use: Before launching Codex/AI-assisted edits, when crafting prompts, or when aligning work with current documentation initiatives</p>"},{"location":"documentation-index/#readmemd","title":"README.md \ud83d\udccb","text":"<p>Project overview and compatibility matrix</p> <p>Contents: - Project description and features - OpenWrt version compatibility (24.10.x, 25.12.0-rc1, etc.) - Package format support (.ipk vs .apk) - Installation instructions - Module categories and descriptions</p> <p>When to use: Project overview, version compatibility checks</p>"},{"location":"documentation-index/#2-complete-reference-documents","title":"2. Complete Reference Documents","text":""},{"location":"documentation-index/#development-guidelinesmd","title":"DEVELOPMENT-GUIDELINES.md \u2b50","text":"<p>Complete development guide - The definitive reference</p> <p>Contents: - Design System: Color palettes, typography, component library - Architecture: File structure, naming conventions, RPCD patterns - Best Practices: RPCD, ubus, ACL, JavaScript, CSS standards - Common Errors: Diagnostics and solutions for typical issues - Validation: Pre-commit, pre-deploy, post-deploy checklists - Deployment: Step-by-step deployment procedures</p> <p>When to use: Detailed technical questions, design decisions, troubleshooting</p> <p>Size: Comprehensive (~500+ lines)</p>"},{"location":"documentation-index/#claudemd","title":"CLAUDE.md \ud83c\udfd7\ufe0f","text":"<p>Build system, architecture, and CI/CD reference</p> <p>Contents: - OpenWrt SDK build commands - Package testing procedures - Validation tools and workflows - LuCI package structure - Frontend-backend communication - Critical naming conventions - CI/CD integration (GitHub Actions) - Common issues and solutions</p> <p>When to use: Build issues, CI/CD workflows, architecture questions</p>"},{"location":"documentation-index/#3-implementation-regeneration-documents","title":"3. Implementation & Regeneration Documents","text":""},{"location":"documentation-index/#module-implementation-guidemd","title":"MODULE-IMPLEMENTATION-GUIDE.md \ud83c\udfaf","text":"<p>Master guide for implementing/regenerating modules</p> <p>Contents: - Step-by-step workflow for regenerating modules - How to use Claude.ai for code generation - Complete implementation example (from prompt to deployment) - Common implementation patterns (multi-tab dashboards, filters, forms) - Module-specific notes (System Hub, WireGuard, CrowdSec, etc.) - Troubleshooting guide with solutions - Best practices (code organization, error handling, performance, UX) - Deployment checklist</p> <p>When to use: Implementing new modules, regenerating existing modules, using AI assistance</p> <p>Size: Comprehensive guide (~800+ lines)</p>"},{"location":"documentation-index/#feature-regeneration-promptsmd","title":"FEATURE-REGENERATION-PROMPTS.md \ud83d\udcac","text":"<p>Ready-to-use prompts for all 15 SecuBox modules</p> <p>Contents: - Design system reference (CSS variables, typography, components) - Complete prompts for all 15 modules: 1. SecuBox Central Hub 2. System Hub (9 tabs) 3. CrowdSec Dashboard 4. Netdata Dashboard 5. Netifyd Dashboard 6. Network Modes 7. WireGuard Dashboard 8. Client Guardian 9. Auth Guardian 10. Bandwidth Manager 11. Traffic Shaper 12. Media Flow 13. CDN Cache 14. VHost Manager 15. KSM Manager - Common UI patterns across all modules - Usage instructions for Claude.ai</p> <p>When to use: Getting AI to generate module code, understanding module requirements</p> <p>Size: Extensive (~2000+ lines)</p>"},{"location":"documentation-index/#code-templatesmd","title":"CODE-TEMPLATES.md \ud83d\udcbb","text":"<p>Working code templates extracted from production modules</p> <p>Contents: - File structure template - API module template (api.js) - JavaScript view template (overview.js) - RPCD backend template (shell script) - Menu JSON template - ACL JSON template - CSS styling template - Complete minimal working example - Common pitfalls and solutions - Validation checklist</p> <p>When to use: Manual implementation, understanding patterns, copying boilerplate code</p> <p>Size: Detailed templates (~1200+ lines)</p>"},{"location":"documentation-index/#4-embedded-deployment-guides","title":"4. Embedded Deployment Guides","text":""},{"location":"documentation-index/#embeddeddocker-zigbee2mqttmd","title":"embedded/docker-zigbee2mqtt.md \ud83d\udd0c","text":"<p>Deploy Zigbee2MQTT via Docker on SecuBox (ARM64).</p> <p>Pointer: see <code>docs/embedded/docker-zigbee2mqtt.md</code> for the canonical version.</p>"},{"location":"documentation-index/#embeddedvhost-managermd","title":"embedded/vhost-manager.md \ud83c\udf10","text":"<p>How to publish services through nginx using the vhost manager and CLI helper.</p> <p>Pointer: see <code>docs/embedded/vhost-manager.md</code> for the canonical version.</p>"},{"location":"documentation-index/#embeddedapp-storemd","title":"embedded/app-store.md \ud83d\uded2","text":"<p>Manifest schema, <code>secubox-app</code> CLI usage, and packaged SecuBox apps (Zigbee2MQTT, Lyrion, Domoticz).</p> <p>Pointer: see <code>docs/embedded/app-store.md</code> for the canonical version.</p>"},{"location":"documentation-index/#embeddedwizard-profilesmd","title":"embedded/wizard-profiles.md \ud83e\udded","text":"<p>First-run wizard and OS-like profiles.</p> <p>Pointer: see <code>docs/embedded/wizard-profiles.md</code> for the canonical version.</p>"},{"location":"documentation-index/#embeddedlyrion-dockermd","title":"embedded/lyrion-docker.md \ud83c\udfb5","text":"<p>Deploy Lyrion Media Server via Docker.</p> <p>Pointer: see <code>docs/embedded/lyrion-docker.md</code> for the canonical version.</p>"},{"location":"documentation-index/#embeddeddomoticz-dockermd","title":"embedded/domoticz-docker.md \ud83c\udfe0","text":"<p>Deploy Domoticz home automation via Docker.</p> <p>Pointer: see <code>docs/embedded/domoticz-docker.md</code> for the canonical version.</p>"},{"location":"documentation-index/#5-tools-scripts-documentation","title":"5. Tools & Scripts Documentation","text":""},{"location":"documentation-index/#secubox-toolsreadmemd","title":"secubox-tools/README.md \ud83d\udd27","text":"<p>Documentation for validation and build tools</p> <p>Contents: - Tool descriptions (validate-modules.sh, local-build.sh, etc.) - Usage examples for each tool - Supported architectures and devices - Package building workflows - Firmware building workflows - Validation checks (7 automated checks) - Recommended workflows - Common fixes</p> <p>When to use: Using validation tools, local builds, firmware generation</p>"},{"location":"documentation-index/#6-live-demo-examples","title":"6. Live Demo & Examples","text":""},{"location":"documentation-index/#live-demo-website","title":"Live Demo Website \ud83c\udf10","text":"<p>Production demo of all modules</p> <p>URL: https://secubox.cybermood.eu</p> <p>Available Demos: - Main dashboard: <code>/</code> - System Hub: <code>/system-hub</code> - CrowdSec: <code>/crowdsec</code> - WireGuard: <code>/wireguard</code> - All 15 modules accessible</p> <p>When to use: Visual reference, understanding UI/UX, testing features</p>"},{"location":"documentation-index/#quick-lookup-by-task","title":"\ud83c\udfaf Quick Lookup by Task","text":""},{"location":"documentation-index/#i-want-to","title":"I want to...","text":""},{"location":"documentation-index/#create-a-new-module-from-scratch","title":"...create a new module from scratch","text":"<ol> <li>Read: MODULE-IMPLEMENTATION-GUIDE.md (Step-by-step workflow)</li> <li>Copy prompt from: FEATURE-REGENERATION-PROMPTS.md</li> <li>Use templates from: CODE-TEMPLATES.md</li> <li>Validate with: <code>./secubox-tools/validate-modules.sh</code></li> </ol>"},{"location":"documentation-index/#regenerate-an-existing-module","title":"...regenerate an existing module","text":"<ol> <li>Read: MODULE-IMPLEMENTATION-GUIDE.md (Section: \"Step-by-Step: Regenerate a Module with Claude.ai\")</li> <li>Copy module specification from: FEATURE-REGENERATION-PROMPTS.md</li> <li>Use Claude.ai or copy templates from: CODE-TEMPLATES.md</li> <li>Validate and deploy following: MODULE-IMPLEMENTATION-GUIDE.md</li> </ol>"},{"location":"documentation-index/#fix-rpcd-object-not-found-error","title":"...fix RPCD \"Object not found\" error","text":"<ol> <li>Quick fix: QUICK-START.md (Error Quick Fixes section)</li> <li>Detailed troubleshooting: DEVELOPMENT-GUIDELINES.md (Common Errors section)</li> <li>Or: MODULE-IMPLEMENTATION-GUIDE.md (Troubleshooting Guide)</li> </ol>"},{"location":"documentation-index/#understand-the-design-system","title":"...understand the design system","text":"<ol> <li>Quick reference: QUICK-START.md (Design System Essentials)</li> <li>Complete guide: DEVELOPMENT-GUIDELINES.md (Design System & UI Guidelines)</li> <li>See live examples: https://secubox.cybermood.eu</li> </ol>"},{"location":"documentation-index/#build-packages-locally","title":"...build packages locally","text":"<ol> <li>Quick commands: QUICK-START.md (Build & Deploy section)</li> <li>Complete guide: secubox-tools/README.md</li> <li>Architecture details: CLAUDE.md (Build Commands section)</li> </ol>"},{"location":"documentation-index/#validate-my-changes-before-commit","title":"...validate my changes before commit","text":"<ol> <li>Run: <code>./secubox-tools/fix-permissions.sh --local</code></li> <li>Run: <code>./secubox-tools/validate-modules.sh</code></li> <li>Review checklist: DEVELOPMENT-GUIDELINES.md (Validation Checklist)</li> </ol>"},{"location":"documentation-index/#understand-menu-and-acl-configuration","title":"...understand menu and ACL configuration","text":"<ol> <li>Quick templates: CODE-TEMPLATES.md (Menu JSON Template, ACL JSON Template)</li> <li>Detailed guide: DEVELOPMENT-GUIDELINES.md (Architecture & Naming Conventions)</li> <li>Working examples: Look in any <code>luci-app-*/root/usr/share/</code> directory</li> </ol>"},{"location":"documentation-index/#deploy-to-test-router","title":"...deploy to test router","text":"<ol> <li>Quick commands: QUICK-START.md (Common Commands)</li> <li>Step-by-step: MODULE-IMPLEMENTATION-GUIDE.md (Deploy to Test Router section)</li> <li>Fix permissions after deploy: <code>./secubox-tools/fix-permissions.sh --remote</code></li> </ol>"},{"location":"documentation-index/#understand-css-variable-system","title":"...understand CSS variable system","text":"<ol> <li>Quick reference: QUICK-START.md (CSS Variables section)</li> <li>Complete guide: DEVELOPMENT-GUIDELINES.md (CSS/Styling Standards)</li> <li>Template: CODE-TEMPLATES.md (CSS Styling Template)</li> <li>Live CSS: <code>luci-app-system-hub/htdocs/luci-static/resources/system-hub/common.css</code></li> </ol>"},{"location":"documentation-index/#write-rpcd-backend-script","title":"...write RPCD backend script","text":"<ol> <li>Template: CODE-TEMPLATES.md (RPCD Backend Template)</li> <li>Best practices: DEVELOPMENT-GUIDELINES.md (RPCD & ubus Best Practices)</li> <li>Working examples: Look in any <code>luci-app-*/root/usr/libexec/rpcd/</code> directory</li> </ol>"},{"location":"documentation-index/#create-multi-tab-dashboard","title":"...create multi-tab dashboard","text":"<ol> <li>Pattern: MODULE-IMPLEMENTATION-GUIDE.md (Pattern 1: Multi-Tab Dashboard)</li> <li>Example: See <code>luci-app-system-hub</code> (9 tabs)</li> <li>Live demo: https://secubox.cybermood.eu/system-hub</li> </ol>"},{"location":"documentation-index/#documentation-comparison-matrix","title":"\ud83d\udcca Documentation Comparison Matrix","text":"Document Size Scope Use Case Audience QUICK-START.md Small Quick reference Daily development All developers README.md Small Project overview First introduction New contributors DEVELOPMENT-GUIDELINES.md Large Complete reference Detailed questions All developers CLAUDE.md Medium Build & architecture Build/CI/CD issues Developers, DevOps MODULE-IMPLEMENTATION-GUIDE.md Large Implementation workflow Module creation AI-assisted dev FEATURE-REGENERATION-PROMPTS.md Very Large Module specifications AI prompts AI-assisted dev CODE-TEMPLATES.md Large Code templates Manual coding Developers secubox-tools/README.md Medium Tools documentation Tool usage Developers, DevOps"},{"location":"documentation-index/#documentation-update-workflow","title":"\ud83d\udd04 Documentation Update Workflow","text":"<p>When making changes to the codebase:</p> <ol> <li>Update code in module files</li> <li>Run validation: <code>./secubox-tools/validate-modules.sh</code></li> <li>Update documentation if:</li> <li>New pattern introduced \u2192 Add to CODE-TEMPLATES.md</li> <li>New design guideline \u2192 Update DEVELOPMENT-GUIDELINES.md</li> <li>New common error \u2192 Add to QUICK-START.md and DEVELOPMENT-GUIDELINES.md</li> <li>New module \u2192 Add to FEATURE-REGENERATION-PROMPTS.md</li> <li>New build feature \u2192 Update CLAUDE.md and secubox-tools/README.md</li> <li>Update version and date in modified documents</li> <li>Commit documentation along with code changes</li> </ol>"},{"location":"documentation-index/#support-contact","title":"\ud83d\udcde Support & Contact","text":"<ul> <li>Documentation Issues: Create issue at GitHub Issues</li> <li>Technical Support: support@cybermind.fr</li> <li>Live Demo: https://secubox.cybermood.eu</li> <li>Company: CyberMind.fr</li> </ul>"},{"location":"documentation-index/#learning-path","title":"\ud83c\udf93 Learning Path","text":""},{"location":"documentation-index/#beginner-new-to-secubox","title":"Beginner (New to SecuBox)","text":"<ol> <li>Day 1: Read README.md + QUICK-START.md</li> <li>Day 2: Skim DEVELOPMENT-GUIDELINES.md (focus on Design System and Architecture)</li> <li>Day 3: Follow MODULE-IMPLEMENTATION-GUIDE.md to implement a simple module</li> <li>Day 4: Study existing modules (start with <code>luci-app-cdn-cache</code> - simplest)</li> <li>Day 5: Make your first contribution</li> </ol>"},{"location":"documentation-index/#intermediate-familiar-with-openwrtluci","title":"Intermediate (Familiar with OpenWrt/LuCI)","text":"<ol> <li>Read DEVELOPMENT-GUIDELINES.md (full document)</li> <li>Review CODE-TEMPLATES.md for patterns</li> <li>Use FEATURE-REGENERATION-PROMPTS.md with Claude.ai to generate a module</li> <li>Study CLAUDE.md for build system details</li> <li>Contribute new modules or enhance existing ones</li> </ol>"},{"location":"documentation-index/#advanced-ready-for-complex-modules","title":"Advanced (Ready for Complex Modules)","text":"<ol> <li>Study complex modules: System Hub, Network Modes</li> <li>Read all documentation for comprehensive understanding</li> <li>Use MODULE-IMPLEMENTATION-GUIDE.md patterns for advanced features</li> <li>Contribute to core design system and tools</li> <li>Help with documentation improvements</li> </ol>"},{"location":"documentation-index/#version-history","title":"\ud83d\udcdd Version History","text":"Version Date Changes 1.0.0 2025-12-27 Initial comprehensive documentation release - Created FEATURE-REGENERATION-PROMPTS.md (15 modules) - Created CODE-TEMPLATES.md (complete templates) - Created MODULE-IMPLEMENTATION-GUIDE.md (master guide) - Created DOCUMENTATION-INDEX.md (this file) - Enhanced existing documentation"},{"location":"documentation-index/#documentation-quality-goals","title":"\ud83c\udfc6 Documentation Quality Goals","text":"<ul> <li>Completeness: All aspects of SecuBox development covered</li> <li>Accuracy: Code examples tested and working</li> <li>Clarity: Clear explanations with examples</li> <li>Maintainability: Easy to update as codebase evolves</li> <li>Accessibility: Multiple entry points for different use cases</li> <li>AI-Friendly: Structured for AI-assisted development</li> </ul> <p>Last Updated: 2025-12-27 Maintainer: CyberMind.fr License: Apache-2.0</p>"},{"location":"feature-regeneration-prompts/","title":"SecuBox Feature Regeneration Prompts","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active Purpose: Comprehensive prompts for Claude.ai to regenerate all SecuBox module features matching the live demo at secubox.cybermood.eu</p>"},{"location":"feature-regeneration-prompts/#see-also","title":"See Also","text":"<ul> <li>Implementation Workflow: MODULE-IMPLEMENTATION-GUIDE.md</li> <li>Code Templates: CODE-TEMPLATES.md</li> <li>Quick Commands: QUICK-START.md</li> <li>Automation Guardrails: CODEX.md</li> </ul>"},{"location":"feature-regeneration-prompts/#table-of-contents","title":"Table of Contents","text":"<ol> <li>Design System Reference</li> <li>Core Modules Prompts</li> <li>Security & Monitoring Modules</li> <li>Network Intelligence Modules</li> <li>VPN & Access Control Modules</li> <li>Bandwidth & Traffic Modules</li> <li>Performance & Services Modules</li> </ol>"},{"location":"feature-regeneration-prompts/#design-system-reference","title":"Design System Reference","text":""},{"location":"feature-regeneration-prompts/#color-palette-variables","title":"Color Palette & Variables","text":"<p>All modules MUST use CSS variables from <code>system-hub/common.css</code>:</p> <p>Dark Mode (Primary): <pre><code>--sh-bg-primary: #0a0a0f; /* Deep black background */\n--sh-bg-secondary: #12121a; /* Card backgrounds */\n--sh-bg-tertiary: #1a1a24; /* Hover/active states */\n--sh-primary: #6366f1; /* Indigo primary */\n--sh-primary-end: #8b5cf6; /* Violet (gradients) */\n--sh-success: #22c55e; /* Green */\n--sh-danger: #ef4444; /* Red */\n--sh-warning: #f59e0b; /* Orange */\n--sh-text-primary: #fafafa; /* Main text */\n--sh-text-secondary: #a0a0b0; /* Secondary text */\n</code></pre></p>"},{"location":"feature-regeneration-prompts/#typography-standards","title":"Typography Standards","text":"<pre><code>/* Fonts */\nInter: Body text, labels, UI elements\nJetBrains Mono: Numbers, IDs, code, metrics\n\n/* Sizes */\n--sh-title-xl: 28px; /* Page titles */\n--sh-title-lg: 20px; /* Card titles */\n--sh-value-xl: 40px; /* Large metrics */\n--sh-value-lg: 32px; /* Stats overview */\n</code></pre>"},{"location":"feature-regeneration-prompts/#component-patterns","title":"Component Patterns","text":"<ol> <li>Page Header: Icon + Title + Subtitle + Stats Grid</li> <li>Stats Badges: Monospace values, 130px minimum width</li> <li>Cards: 3px top border (gradient or solid color)</li> <li>Buttons: Gradient backgrounds, shadow effects, smooth transitions</li> <li>Filter Tabs: Gradient for active, icon + label pattern</li> </ol>"},{"location":"feature-regeneration-prompts/#core-modules-prompts","title":"Core Modules Prompts","text":""},{"location":"feature-regeneration-prompts/#1-secubox-central-hub-luci-app-secubox","title":"1. SecuBox Central Hub (luci-app-secubox)","text":"<p>Module Purpose: Main dashboard and central control panel</p> <p>Prompt for Claude.ai:</p> <pre><code>Create a LuCI dashboard module for SecuBox Central Hub with these features:\n\nDESIGN REQUIREMENTS:\n- Dark theme with gradient backgrounds (#0a0a0f \u2192 #12121a)\n- Page header with rocket icon \ud83d\ude80 and title \"SecuBox Control Center\"\n- Stats grid showing: Total Modules (badge), Active Services, System Health, Alerts Count\n- Use CSS variables from --sh-* (never hardcode colors)\n\nMAIN FEATURES:\n1. Module Overview Grid\n - Display all 15 installed SecuBox modules as cards\n - Each card: Module icon, name, status badge (active/inactive), version\n - Color-coded borders: green (running), orange (warning), red (stopped)\n - \"Configure\" and \"View Details\" buttons per card\n - Filter tabs: All | Security | Network | Services\n\n2. System Health Dashboard\n - Real-time metrics: CPU, RAM, Disk, Network\n - Animated progress bars with gradient fills\n - Threshold indicators (warn >80%, danger >90%)\n - JetBrains Mono font for all numeric values\n\n3. Quick Actions Panel\n - Restart All Services button (gradient orange)\n - Update Packages button (gradient blue)\n - View System Logs button (gradient indigo)\n - Export Config button (gradient green)\n\n4. Alert Timeline\n - Last 10 system events with timestamps\n - Icon indicators for severity levels\n - Expandable details per alert\n - Auto-refresh every 30 seconds\n\nTECHNICAL SPECS:\n- File: luci-app-secubox/htdocs/luci-static/resources/view/secubox/dashboard.js\n- RPCD backend: luci.secubox (methods: getModules, getHealth, getAlerts)\n- CSS: luci-app-secubox/htdocs/luci-static/resources/secubox/dashboard.css\n- Use L.resolveDefault() for all ubus calls\n- Implement proper error handling with user-friendly messages\n- Add loading states with skeleton screens\n\nUI COMPONENTS TO USE:\n- sh-page-header for main header\n- sh-card with sh-card-success/warning/danger variants\n- sh-stat-badge for metrics (130px minimum)\n- sh-btn sh-btn-primary for action buttons\n- sh-filter-tabs for category filtering\n\nREFERENCE THE LIVE DEMO:\nMatch the look and feel of secubox.cybermood.eu demo\n- Smooth animations on card hover\n- Gradient text effects on titles\n- Glow effects on active elements\n- Responsive grid (min 280px cards)\n</code></pre>"},{"location":"feature-regeneration-prompts/#2-system-hub-luci-app-system-hub","title":"2. System Hub (luci-app-system-hub)","text":"<p>Module Purpose: Unified system control center</p> <p>Prompt for Claude.ai:</p> <pre><code>Create a comprehensive System Hub module for OpenWrt with these features:\n\nDESIGN REQUIREMENTS:\n- Use System Hub design system (common.css variables)\n- Page title: \"System Control Center\" with \u2699\ufe0f icon\n- Multi-tab interface: Overview | Services | Logs | Backup | Components | Diagnostics | Health | Remote | Settings\n\nOVERVIEW TAB:\n1. System Info Grid (4 columns, responsive)\n - Hostname card with edit button\n - Uptime card with formatted duration\n - Load Average card (1m, 5m, 15m) in monospace\n - Kernel Version card with copy icon\n\n2. Resource Monitors (animated progress circles)\n - CPU usage with color coding (<70% green, 70-90% orange, >90% red)\n - Memory usage with used/total display\n - Storage usage with filesystem breakdown\n - Network throughput (RX/TX rates in real-time)\n\n3. Quick Status Indicators\n - Internet connectivity (ping test every 60s)\n - DNS resolution status\n - NTP sync status\n - Firewall status with rule count\n\nSERVICES TAB:\n1. Service Cards Grid\n - Each service: name, status badge, description, uptime\n - Color-coded borders based on status\n - Action buttons: Start/Stop/Restart/Enable/Disable\n - Filter by: All | Running | Stopped | Enabled | Disabled\n - Search bar for filtering services\n\n2. Service Details Modal\n - Full service info (PID, memory usage, CPU time)\n - Recent logs (last 50 lines with syntax highlighting)\n - Configuration file path with edit link\n - Dependencies tree view\n\nLOGS TAB:\n1. System Logs Viewer\n - Real-time log streaming (WebSocket or polling)\n - Color-coded severity levels (error=red, warn=orange, info=blue)\n - Filter by: severity, service, date range\n - Search functionality with regex support\n - Auto-scroll toggle\n - Export logs button (download as .txt)\n - Line numbers in monospace\n - Compact header mode (saves vertical space)\n\n2. Log Statistics\n - Error count in last hour/day\n - Most active services\n - Alert frequency chart (sparkline)\n\nBACKUP TAB:\n1. Backup Management\n - Create backup button (includes config + installed packages list)\n - List existing backups with date, size, description\n - Restore from backup with confirmation modal\n - Download backup to local machine\n - Upload backup from file\n - Auto-backup schedule configuration\n\n2. Backup Preview\n - Show included files before creating\n - Estimated size calculation\n - Compression options (gz, xz)\n\nCOMPONENTS TAB:\n1. Installed Packages Display\n - Grid of all luci-app-* packages\n - Each card: package name, version, size, status\n - Category filtering (same as SecuBox modules)\n - Dependency information\n - Uninstall button with warning\n\nDIAGNOSTICS TAB:\n1. Network Diagnostics\n - Ping tool with target input\n - Traceroute with hop visualization\n - DNS lookup with multiple nameservers\n - Port scanner (common ports or custom range)\n - Bandwidth test (speedtest-cli integration)\n\n2. System Diagnostics\n - Filesystem check status\n - Memory leak detection\n - Process list with resource usage\n - Open file descriptors count\n - Network connections table\n\nHEALTH TAB:\n1. System Health Report\n - Overall health score (0-100) with gradient circle\n - Critical issues list with fix suggestions\n - Temperature sensors (if available)\n - Fan speeds (if available)\n - SMART disk status\n - Battery status (for UPS-backed systems)\n\n2. Health History\n - 24h health score chart (line graph)\n - Resource usage trends\n - Alert frequency over time\n\nREMOTE TAB:\n1. Remote Access Management\n - SSH status with port and allowed IPs\n - Web UI access info (HTTP/HTTPS, port, external access)\n - RustDesk remote desktop integration\n - WireGuard VPN status (if installed)\n - Dynamic DNS configuration\n\nSETTINGS TAB:\n1. System Hub Preferences\n - Auto-refresh interval (10s/30s/60s/disabled)\n - Dark/Light mode toggle\n - Compact mode toggle\n - Language selection\n - Timezone configuration\n - Dashboard layout customization\n\nTECHNICAL IMPLEMENTATION:\n- Files: system-hub/overview.js, services.js, logs.js, backup.js, components.js, diagnostics.js, health.js, remote.js, settings.js\n- RPCD: luci.system-hub with methods for each feature\n- API file: system-hub/api.js with clean method wrappers\n- CSS: system-hub/dashboard.css + common.css\n- Use theme.js for dark/light mode switching\n- WebSocket support for real-time log streaming\n- LocalStorage for user preferences\n- Proper loading states and error handling\n\nREFERENCE DEMO:\nMatch secubox.cybermood.eu/system-hub demo\n- Smooth tab transitions\n- Real-time data updates\n- Responsive grid layouts\n- Professional color coding\n</code></pre>"},{"location":"feature-regeneration-prompts/#security-monitoring-modules","title":"Security & Monitoring Modules","text":""},{"location":"feature-regeneration-prompts/#3-crowdsec-dashboard-luci-app-crowdsec-dashboard","title":"3. CrowdSec Dashboard (luci-app-crowdsec-dashboard)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a CrowdSec security monitoring dashboard for OpenWrt:\n\nDESIGN:\n- Title: \"CrowdSec Security\" with \ud83d\udee1\ufe0f icon\n- Dark theme with emphasis on threat indicators\n- Stats badges: Active Decisions | Blocked IPs | Alerts | Bouncers\n\nOVERVIEW TAB:\n1. Threat Intelligence Summary\n - Total decisions count (15M+ IPs blocked globally reference)\n - Active local decisions with expiry countdown\n - Decision types breakdown (ban, captcha, throttle) as pie chart\n - Country distribution of threats (top 10 with flags)\n\n2. Recent Alerts Timeline\n - Alert cards with: timestamp, scenario, IP, country flag, severity\n - Color-coded by risk level\n - Expandable details showing full event data\n - Filter by: time range, scenario type, severity\n\n3. Real-time Activity Feed\n - Last 100 events (scrollable, auto-updating)\n - IP address in monospace with copy button\n - Scenario name with icon\n - Action taken (ban/log/captcha)\n\nDECISIONS TAB:\n1. Active Decisions Table\n - Columns: IP, Reason, Duration, Expires In, Type, Origin, Actions\n - Sortable by all columns\n - Search and filter capabilities\n - Manual decision add/remove buttons\n - Bulk actions (delete selected)\n - Export to CSV button\n\n2. Decision Statistics\n - Decisions over time (24h chart)\n - Most blocked IPs\n - Most triggered scenarios\n - Average decision duration\n\nALERTS TAB:\n1. Alert Management\n - Alert cards grouped by scenario\n - Timeline view with date headers\n - Severity indicators (critical/high/medium/low)\n - Related decisions linking\n - Mark as resolved functionality\n\nBOUNCERS TAB:\n1. Bouncer Status\n - Connected bouncers list\n - Each bouncer: name, type, version, last pull, status\n - Add new bouncer with API key generation\n - Delete bouncer with confirmation\n - Bouncer metrics (decisions applied, queries made)\n\nMETRICS TAB:\n1. Performance Metrics\n - CrowdSec service health\n - Decision pull frequency\n - API response times\n - Memory and CPU usage\n - LAPI/CAPI status indicators\n\nSETTINGS TAB:\n1. CrowdSec Configuration\n - Enable/disable service\n - Acquisition configuration (log paths)\n - Scenario management (enable/disable specific scenarios)\n - Collection management (install/remove)\n - Console enrollment status\n\nTECHNICAL:\n- RPCD: luci.crowdsec-dashboard\n- Methods: getStats, getDecisions, getAlerts, getBouncers, getMetrics\n- Commands: cscli decisions list/add/delete, cscli alerts list, cscli bouncers list\n- Parse JSON output from cscli commands\n- Handle API communication with CrowdSec daemon\n\nVISUAL ENHANCEMENTS:\n- Gradient borders for threat level cards (green\u2192orange\u2192red)\n- Animated pulse on new alerts\n- Country flags for IP geolocation\n- Sparkline charts for metrics\n- Loading skeletons during data fetch\n</code></pre>"},{"location":"feature-regeneration-prompts/#4-netdata-dashboard-luci-app-netdata-dashboard","title":"4. Netdata Dashboard (luci-app-netdata-dashboard)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a Netdata system monitoring dashboard with 1000+ metrics:\n\nDESIGN:\n- Title: \"System Monitoring\" with \ud83d\udcca icon\n- Emphasis on real-time charts and metrics\n- Stats badges: Alerts | Services | Charts | Collectors\n\nDASHBOARD TAB:\n1. Overview Metrics Grid\n - System load (1m, 5m, 15m) as gauge charts\n - CPU usage per core (multi-core visualization)\n - RAM usage with breakdown (used/cached/buffers/free)\n - Disk I/O rates (read/write MB/s)\n - Network throughput (all interfaces combined)\n\n2. Quick Charts\n - CPU temperature chart (if available)\n - Swap usage chart\n - Processes count chart (running/sleeping/zombie)\n - Context switches and interrupts chart\n\n3. Embedded Netdata\n - Full Netdata web UI embedded in iframe\n - Responsive sizing\n - Theme matching (dark mode)\n\nSYSTEM TAB:\n1. System Metrics Deep Dive\n - CPU frequency and governor\n - CPU idle time percentage\n - Per-core usage bars\n - System interrupts per second\n - Context switches rate\n - Kernel internal metrics\n\n2. Memory Details\n - Memory allocation chart\n - Page faults rate\n - Committed memory ratio\n - Huge pages usage\n - Slab memory breakdown\n\nPROCESSES TAB:\n1. Process Monitoring\n - Top processes by CPU (live updating table)\n - Top processes by RAM\n - Process count by state\n - Thread count total\n - Process spawn rate\n\n2. Process Details\n - Per-process CPU time\n - Per-process memory maps\n - Open files per process\n - Process tree visualization\n\nREALTIME TAB:\n1. Live Monitoring\n - Real-time CPU chart (1s granularity)\n - Real-time network I/O\n - Real-time disk I/O\n - Real-time memory changes\n - Auto-refreshing every second\n\nNETWORK TAB:\n1. Network Metrics\n - Interface statistics (all interfaces)\n - Packet rates (packets/s in/out)\n - Error and drop counters\n - TCP/UDP connection states\n - Netfilter statistics\n - DNS query statistics (if available)\n\nSETTINGS TAB:\n1. Netdata Configuration\n - Enable/disable Netdata service\n - Configure retention period\n - Enable/disable specific collectors\n - Alert configuration\n - Streaming configuration (central Netdata)\n\nTECHNICAL:\n- RPCD: luci.netdata-dashboard\n- Netdata API integration (http://localhost:19999/api/v1/)\n- Methods: /info, /charts, /data, /alarms\n- Real-time data fetching with polling\n- Chart.js or native Netdata charts\n- WebSocket support for live updates\n\nCHARTS TO INCLUDE:\n- Line charts for time-series data\n- Bar charts for comparisons\n- Gauge charts for current values\n- Area charts for stacked metrics\n- Sparklines for compact overviews\n</code></pre>"},{"location":"feature-regeneration-prompts/#network-intelligence-modules","title":"Network Intelligence Modules","text":""},{"location":"feature-regeneration-prompts/#5-netifyd-dashboard-luci-app-netifyd-dashboard","title":"5. Netifyd Dashboard (luci-app-netifyd-dashboard)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a Deep Packet Inspection dashboard using Netifyd (300+ app detection):\n\nDESIGN:\n- Title: \"Network Intelligence\" with \ud83d\udd0d icon\n- Focus on application and protocol visibility\n- Stats badges: Active Flows | Applications | Devices | Protocols\n\nOVERVIEW TAB:\n1. Network Activity Summary\n - Total flows count (current + historical)\n - Unique applications detected today\n - Active devices count\n - Protocol distribution (TCP/UDP/ICMP pie chart)\n\n2. Top Applications Chart\n - Bar chart of top 10 applications by bandwidth\n - Icons for recognized apps (Netflix, YouTube, Spotify, etc.)\n - Percentage of total traffic\n - Click to filter flows by application\n\n3. Top Devices\n - Device cards with: hostname, MAC, IP, current app\n - Bandwidth usage per device (RX/TX)\n - Device type icon (phone, laptop, TV, IoT)\n\nAPPLICATIONS TAB:\n1. Application Discovery\n - Grid of detected applications\n - Each card: app icon, name, category, protocol, active flows\n - Color-coded categories:\n * Streaming (red): Netflix, YouTube, Twitch\n * Social (blue): Facebook, Instagram, TikTok\n * Messaging (green): WhatsApp, Telegram, Signal\n * VoIP (purple): Zoom, Teams, Discord\n * Gaming (orange): Steam, PlayStation, Xbox\n - Real-time bandwidth per app (sparklines)\n\n2. Application Details\n - Click app to see: active connections, total bandwidth, protocols used\n - Flow timeline for selected app\n - Device breakdown (which devices use this app)\n\nDEVICES TAB:\n1. Device Inventory\n - Table: IP, MAC, Hostname, Vendor, Active Apps, Bandwidth\n - Sortable and searchable\n - Device grouping by subnet\n - Manual device naming/tagging\n\n2. Device Profile\n - Per-device view: all flows, app usage history\n - Bandwidth trends (24h chart)\n - Risk assessment (unknown protocols, suspicious apps)\n - Block/allow rules management\n\nFLOWS TAB:\n1. Active Flows Monitor\n - Real-time table of network flows\n - Columns: Source, Destination, App, Protocol, Bandwidth, Duration\n - Auto-scrolling with pause button\n - Color-coded by risk level\n - Flow details on click (full 5-tuple + DPI data)\n\n2. Flow Statistics\n - Flows by protocol (pie chart)\n - Top talkers (source IPs)\n - Top destinations (external IPs)\n - Port distribution\n\nTOP TALKERS TAB:\n1. Bandwidth Leaders\n - Ranked list of IP addresses by total traffic\n - Direction indicators (upload/download)\n - Time range selector (1h/24h/7d/30d)\n - Export to CSV\n\nRISKS TAB:\n1. Risk Assessment\n - Suspicious flows detection\n - Unknown protocols list\n - Connections to blacklisted IPs\n - Unusual port usage\n - Potential malware C2 traffic\n - Risk score per device (0-100)\n\nCATEGORY BANDWIDTH TAB:\n1. Traffic by Category\n - Stacked area chart showing categories over time\n - Categories: Streaming, Social, Gaming, Business, Other\n - Percentage breakdown\n - Peak usage times\n\nDNS QUERIES TAB:\n1. DNS Analytics\n - Recent DNS queries table\n - Most queried domains\n - Failed queries count\n - DNS leak detection\n - Blocked queries (if using DNS filtering)\n\nSETTINGS TAB:\n1. Netifyd Configuration\n - Enable/disable DPI\n - Select interfaces to monitor\n - Application detection sensitivity\n - Flow export configuration\n - Privacy settings (data retention)\n\nTECHNICAL:\n- RPCD: luci.netifyd-dashboard\n- Netifyd API: Unix socket /var/run/netifyd/netifyd.sock\n- JSON flow export parsing\n- Application database from Netify signatures\n- Real-time flow updates (WebSocket or SSE)\n\nVISUAL FEATURES:\n- Application icons from FontAwesome or custom SVG set\n- Animated flow counters (counting up effect)\n- Color-coded bandwidth bars\n- Interactive charts (click to filter)\n- Tooltips with detailed info\n</code></pre>"},{"location":"feature-regeneration-prompts/#6-network-modes-luci-app-network-modes","title":"6. Network Modes (luci-app-network-modes)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a Network Mode Configuration wizard with 5 topology options:\n\nDESIGN:\n- Title: \"Network Configuration\" with \ud83c\udf10 icon\n- Wizard-style interface with step progression\n- Large mode cards with illustrations\n\nOVERVIEW TAB:\n1. Current Mode Display\n - Large card showing active mode with icon\n - Mode description\n - Current network config summary (WAN/LAN IPs, DHCP status)\n - \"Change Mode\" button (gradient)\n\n2. Mode Comparison Table\n - All 5 modes in columns\n - Rows: Use case, WAN ports, LAN ports, WiFi role, DHCP server, NAT\n - Highlight current mode\n\nWIZARD TAB:\n1. Mode Selection Screen\n - 5 mode cards in grid:\n * Router Mode \ud83c\udfe0 - Default home/office setup\n * Bridge Mode \ud83c\udf09 - Transparent layer-2 forwarding\n * Access Point Mode \ud83d\udce1 - WiFi only, wired uplink\n * Repeater/Extender Mode \ud83d\udd01 - WiFi to WiFi repeating\n * Travel Router Mode \u2708\ufe0f - Portable WiFi from hotel ethernet\n - Each card: title, description, pros/cons, diagram\n - \"Select\" button per card\n\n2. Configuration Screen (per mode)\n - Mode-specific settings:\n * Router: WAN type (DHCP/PPPoE/Static), LAN subnet, DHCP range\n * Bridge: Bridge members, STP enable, VLAN config\n * AP: Uplink interface, SSID, security, channel\n * Repeater: Source SSID scan, credentials, rebroadcast SSID\n * Travel Router: Client WiFi scan, WAN MAC clone option\n\n3. Preview Screen\n - Show configuration changes before applying\n - Network diagram with new topology\n - List of services that will be reconfigured\n - Estimated downtime warning\n - \"Apply\" and \"Back\" buttons\n\n4. Apply Screen\n - Progress indicator during application\n - Step-by-step status:\n * Stopping services...\n * Updating network config...\n * Restarting interfaces...\n * Starting services...\n - Rollback timer (60 seconds to confirm)\n - Confirmation screen after success\n\nROUTER MODE TAB:\n1. Router Settings\n - WAN interface config (DHCP client, static, PPPoE, 3G/4G)\n - LAN interface config (IP, netmask, DHCP server)\n - Port mapping (which physical ports are WAN vs LAN)\n - NAT and firewall rules\n - DNS forwarder configuration\n\nACCESS POINT TAB:\n1. AP Settings\n - Uplink interface selection (ethernet or WiFi)\n - Disable NAT and DHCP server\n - Bridge LAN and Uplink\n - WiFi configuration (SSID, security, channel, power)\n - Fast roaming (802.11r) settings\n\nRELAY TAB:\n1. Relay/Repeater Settings\n - Site survey (scan for WiFi networks)\n - Connect to upstream WiFi (credentials)\n - Rebroadcast SSID (same or different)\n - WiFi to WiFi bridge config\n - Signal strength indicators\n\nSNIFFER MODE TAB:\n1. Packet Capture Configuration\n - Monitor mode on WiFi\n - Promiscuous mode on ethernet\n - Capture filters (BPF syntax)\n - Output format (pcap, pcapng)\n - Capture rotation and storage\n - Integration with tcpdump/wireshark\n\nSETTINGS TAB:\n1. Advanced Network Settings\n - VLAN configuration\n - Link aggregation (bonding)\n - QoS settings\n - IPv6 configuration\n - Custom routing rules\n\nTECHNICAL:\n- RPCD: luci.network-modes\n- Methods: get_current_mode, get_available_modes, set_mode, validate_config\n- UCI config manipulation (/etc/config/network, wireless, firewall, dhcp)\n- Interface state monitoring (network.interface events)\n- Rollback mechanism (uci revert + timer)\n\nVALIDATION:\n- IP address format validation\n- Subnet overlap detection\n- DHCP range within subnet check\n- WiFi channel availability check\n- Physical port assignment conflicts\n</code></pre>"},{"location":"feature-regeneration-prompts/#vpn-access-control-modules","title":"VPN & Access Control Modules","text":""},{"location":"feature-regeneration-prompts/#7-wireguard-dashboard-luci-app-wireguard-dashboard","title":"7. WireGuard Dashboard (luci-app-wireguard-dashboard)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a WireGuard VPN management dashboard with QR code generation:\n\nDESIGN:\n- Title: \"WireGuard VPN\" with \ud83d\udd10 icon\n- Modern VPN dashboard aesthetic\n- Stats badges: Active Peers | Data Transferred | Uptime | Endpoints\n\nOVERVIEW TAB:\n1. VPN Status\n - Interface status (up/down) with toggle\n - Public key display (monospace, copy button)\n - Listen port\n - IP address (VPN subnet)\n - Endpoint (if client mode)\n\n2. Peer Statistics\n - Active peers count\n - Total data RX/TX (all peers combined)\n - Latest handshake timestamp\n - Connection quality indicators\n\n3. Quick Actions\n - Start/Stop VPN button\n - Generate New Keypair button\n - Download Config button\n - Add Peer button (quick modal)\n\nPEERS TAB:\n1. Peer Management\n - Peer cards grid:\n * Each card: name, public key (truncated), allowed IPs, endpoint, status\n * Color-coded border (green=active, orange=stale, red=disconnected)\n * Last handshake time (e.g., \"2 minutes ago\")\n * Data transfer counters (RX/TX)\n * Edit and Delete buttons\n\n2. Add Peer Dialog\n - Generate keypair automatically OR paste existing public key\n - Assign VPN IP address (auto-suggest next available)\n - Define allowed IPs (0.0.0.0/0 for full tunnel, specific subnets for split)\n - Optional: persistent keepalive interval\n - Optional: pre-shared key (PSK) for post-quantum security\n - Generate config file and QR code instantly\n\nQR CODES TAB:\n1. Mobile Client Setup\n - Select peer from dropdown\n - Generate WireGuard client config\n - Display as QR code (for WireGuard mobile app scanning)\n - Also show config text (copyable)\n - Download .conf file button\n - Include DNS servers in config\n\n2. QR Code Options\n - Custom DNS servers\n - Include all routes vs split tunnel\n - MTU configuration\n - Persistent keepalive setting\n\nTRAFFIC TAB:\n1. Traffic Analytics\n - Real-time bandwidth chart (per peer)\n - Historical traffic graph (24h, 7d, 30d)\n - Top bandwidth users\n - Traffic by protocol (if DPI available)\n\nCONFIG TAB:\n1. Interface Configuration\n - Private key (hidden by default, show button)\n - Public key (derived, read-only)\n - Listen port (51820 default)\n - IP addresses (comma-separated for multi-subnet)\n - MTU size\n - Table (routing table number)\n\n2. Advanced Settings\n - Pre-up/Post-up scripts\n - Pre-down/Post-down scripts\n - Firewall zone assignment\n - NAT masquerading toggle\n\nSETTINGS TAB:\n1. Global VPN Settings\n - Auto-start on boot toggle\n - Keep-alive interval (global default)\n - DNS leak protection\n - IPv6 support toggle\n - Logging level\n\n2. Endpoint Configuration (for client mode)\n - Server endpoint hostname/IP\n - Server public key\n - Allowed IPs (what routes through VPN)\n - Persistent keepalive for NAT traversal\n\nTECHNICAL:\n- RPCD: luci.wireguard-dashboard\n- Methods: status, get_interfaces, get_peers, add_peer, remove_peer, generate_keys, generate_config, generate_qr\n- Commands: wg show, wg set, wg genkey, wg pubkey, wg genpsk\n- QR code generation: qrencode command or JavaScript library (qrcodejs)\n- Config file template generation\n- Real-time peer status updates\n\nUI ENHANCEMENTS:\n- Animated connection status indicators\n- Gradient border for active peers\n- Copy-to-clipboard for keys and configs\n- Modal dialogs for add/edit peer\n- Confirmation dialogs for destructive actions\n- Toast notifications for success/error\n</code></pre>"},{"location":"feature-regeneration-prompts/#8-client-guardian-luci-app-client-guardian","title":"8. Client Guardian (luci-app-client-guardian)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a Network Access Control (NAC) and Captive Portal system:\n\nDESIGN:\n- Title: \"Access Control\" with \ud83d\udc65 icon\n- Focus on device management and access policies\n- Stats badges: Total Devices | Allowed | Blocked | Guest\n\nOVERVIEW TAB:\n1. Network Summary\n - Total devices seen (ever)\n - Currently connected devices\n - Allowed devices count\n - Blocked devices count\n - Guest devices (captive portal)\n\n2. Recent Activity\n - Last 20 connection events\n - Each event: timestamp, MAC, IP, hostname, action (allow/block/captive)\n - Color-coded by action type\n\n3. Quick Actions\n - Block All Unknown button (lockdown mode)\n - Allow All button (open mode)\n - Clear Guest Sessions button\n\nCLIENTS TAB:\n1. Device Table\n - Columns: MAC, IP, Hostname, Vendor, Zone, Status, Actions\n - Sortable by all columns\n - Search/filter bar\n - Bulk selection for actions\n\n2. Device Details Modal\n - Full device info: MAC, IP, Hostname, Vendor (from MAC prefix)\n - Connection history (first seen, last seen, total connections)\n - Current zone assignment (LAN, Guest, Blocked)\n - Assigned policies\n - Edit button (change hostname, zone, policies)\n\nZONES TAB:\n1. Zone Management\n - Predefined zones:\n * Trusted (full access)\n * LAN (standard access)\n * Guest (restricted access, captive portal)\n * IoT (isolated, limited access)\n * Quarantine (blocked)\n\n2. Zone Configuration\n - Per-zone settings:\n * Allowed services (HTTP, HTTPS, DNS, etc.)\n * Bandwidth limits\n * Time restrictions\n * Inter-zone communication rules\n * Firewall rules\n\nCAPTIVE PORTAL TAB:\n1. Captive Portal Configuration\n - Enable/disable portal\n - Splash page customization:\n * Custom logo upload\n * Welcome message (HTML editor)\n * Terms of Service text\n * Redirect URL after acceptance\n\n2. Portal Themes\n - Predefined themes (Business, Hotel, Cafe, School)\n - Color scheme customization\n - Preview button\n\n3. Portal Settings\n - Session duration (1h, 4h, 24h, unlimited)\n - Require email before access\n - Require SMS verification\n - Require social login (Facebook, Google)\n - Auto-allow known devices\n\nPORTAL DESIGN TAB:\n1. Splash Page Editor\n - WYSIWYG HTML editor\n - Template variables (e.g., {{client_mac}}, {{client_ip}})\n - Background image upload\n - CSS styling panel\n - Live preview\n\nLOGS TAB:\n1. Access Logs\n - Connection attempts log\n - Allowed/blocked decisions\n - Captive portal authentications\n - Filter by: time range, MAC, IP, zone, action\n\nALERTS TAB:\n1. Security Alerts\n - MAC spoofing detection\n - Excessive connection attempts\n - Unknown devices connecting\n - Devices changing zones\n - Alert rules configuration\n\nPARENTAL CONTROLS TAB:\n1. Content Filtering\n - Website category blocking (adult, social, gaming, etc.)\n - Time-based access controls (school hours, bedtime)\n - Per-device or per-user policies\n - SafeSearch enforcement\n - YouTube restricted mode\n\n2. Device Groups\n - Group devices (e.g., \"Kids Devices\")\n - Apply policies to groups\n - Schedule-based rules (weekday vs weekend)\n\nSETTINGS TAB:\n1. Client Guardian Settings\n - Default zone for new devices\n - MAC-IP binding enforcement\n - ARP cache timeout\n - DHCP integration (assign zone based on IP range)\n - Logging level and retention\n\nTECHNICAL:\n- RPCD: luci.client-guardian\n- Methods: list_clients, update_client, get_zones, configure_portal, get_logs\n- Integration with:\n * nftables/iptables for access control\n * dnsmasq for DNS and DHCP\n * nginx/uhttpd for captive portal\n * ipset for efficient device grouping\n- Database for device tracking (SQLite or UCI)\n\nCAPTIVE PORTAL IMPLEMENTATION:\n- Intercept HTTP traffic for unauthenticated clients\n- Redirect to splash page\n- After acceptance, add to allowed ipset\n- Session management with cookies or tokens\n</code></pre>"},{"location":"feature-regeneration-prompts/#9-auth-guardian-luci-app-auth-guardian","title":"9. Auth Guardian (luci-app-auth-guardian)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create an authentication and session management system with OAuth2 and vouchers:\n\nDESIGN:\n- Title: \"Authentication\" with \ud83d\udd11 icon\n- Professional authentication dashboard\n- Stats badges: Active Sessions | OAuth Providers | Vouchers | Bypass Rules\n\nOVERVIEW TAB:\n1. Authentication Status\n - Total registered users\n - Active sessions count\n - OAuth providers configured\n - Voucher redemptions today\n\n2. Recent Authentications\n - Last 20 auth events\n - Each: timestamp, username/email, method (OAuth/voucher/bypass), IP, status\n - Color-coded by status (success=green, fail=red)\n\nSESSIONS TAB:\n1. Active Sessions Table\n - Columns: User, Session ID, Started, Last Activity, IP, Device, Actions\n - Session details on click\n - Revoke session button (with confirmation)\n - Force logout all sessions button\n\n2. Session Management\n - Session timeout configuration\n - Concurrent session limit per user\n - Idle timeout\n - Remember me duration\n\nVOUCHERS TAB:\n1. Voucher Management\n - Create new voucher button\n - Voucher table: Code, Duration, Remaining Uses, Created, Expires, Status\n - Voucher types:\n * Single-use (one time only)\n * Multi-use (X redemptions)\n * Time-limited (expires after duration)\n * Bandwidth-limited (X GB quota)\n\n2. Create Voucher Dialog\n - Generate random code OR custom code\n - Voucher duration (1h, 4h, 24h, 7d, 30d, unlimited)\n - Usage limit (1, 10, 100, unlimited)\n - Bandwidth quota (optional)\n - Notes/description field\n - Print voucher button (printable page with code)\n\n3. Bulk Voucher Generation\n - Generate X vouchers at once\n - Export as CSV\n - Print sheet (multiple vouchers per page)\n\nOAUTH TAB:\n1. OAuth Provider Configuration\n - Supported providers:\n * Google OAuth\n * GitHub OAuth\n * Facebook Login\n * Microsoft Azure AD\n * Custom OAuth2 provider\n\n2. Provider Setup\n - Client ID input\n - Client Secret input (masked)\n - Redirect URI (auto-generated)\n - Scopes configuration\n - Enable/disable per provider\n - Test button (initiates OAuth flow)\n\n3. User Mapping\n - Map OAuth attributes to local user fields\n - Auto-create user on first OAuth login\n - Group assignment based on OAuth claims\n\nSPLASH PAGE TAB:\n1. Login Page Customization\n - Custom logo upload\n - Welcome text editor\n - Enabled auth methods (OAuth buttons, voucher input, bypass link)\n - Background image or gradient\n - Color scheme\n - Preview button\n\nBYPASS RULES TAB:\n1. Bypass Configuration\n - Whitelist MAC addresses (no auth required)\n - Whitelist IP ranges\n - Whitelist hostnames (regex patterns)\n - Time-based bypass (e.g., office hours, all devices allowed)\n\n2. Bypass List\n - Table: MAC/IP, Description, Added, Expires\n - Add/remove bypass rules\n - Temporary bypass (expires after X hours)\n\nLOGS TAB:\n1. Authentication Logs\n - All auth attempts (success and failure)\n - Filter by: date range, username, method, IP\n - Export to CSV\n - Visualizations:\n * Auth attempts over time (line chart)\n * Auth methods breakdown (pie chart)\n * Failed attempts by IP (bar chart)\n\nSETTINGS TAB:\n1. Auth Guardian Settings\n - Require authentication (global toggle)\n - Default session duration\n - Password policy (if local users)\n - Two-factor authentication (TOTP)\n - Login attempt limits (brute force protection)\n - Session storage (memory vs database)\n\nTECHNICAL:\n- RPCD: luci.auth-guardian\n- Methods: status, list_providers, list_vouchers, create_voucher, delete_voucher, validate_voucher, list_sessions, revoke_session\n- OAuth implementation:\n * Authorization code flow\n * JWT token validation\n * Provider-specific API calls\n- Voucher system:\n * Random code generation (alphanumeric, 8-16 chars)\n * Expiry tracking (cron job or daemon)\n * Redemption logging\n- Session management:\n * Cookie-based or token-based\n * Redis or in-memory storage for sessions\n * Session cleanup task\n\nINTEGRATION:\n- Works with Client Guardian for captive portal\n- Firewall integration for post-auth access\n- RADIUS support (optional, for enterprise)\n</code></pre>"},{"location":"feature-regeneration-prompts/#bandwidth-traffic-modules","title":"Bandwidth & Traffic Modules","text":""},{"location":"feature-regeneration-prompts/#10-bandwidth-manager-luci-app-bandwidth-manager","title":"10. Bandwidth Manager (luci-app-bandwidth-manager)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a comprehensive QoS and bandwidth management system:\n\nDESIGN:\n- Title: \"Bandwidth Manager\" with \ud83d\udcf6 icon\n- Focus on traffic shaping and quotas\n- Stats badges: Active Rules | Total Bandwidth | Clients Tracked | Quotas\n\nOVERVIEW TAB:\n1. Bandwidth Summary\n - Total available bandwidth (WAN uplink/downlink)\n - Current usage (real-time gauge)\n - Peak usage (today's maximum)\n - Average usage (24h)\n\n2. Top Bandwidth Users\n - Table: IP/Hostname, Download, Upload, Total, Percentage\n - Real-time updates\n - Click to apply quick rule\n\n3. Traffic Classification\n - By protocol: HTTP, HTTPS, DNS, P2P, Streaming, Gaming\n - By priority: High, Medium, Low, Bulk\n - Pie chart visualization\n\nRULES TAB:\n1. QoS Rules Table\n - Columns: Name, Source, Destination, Service, Priority, Rate Limit, Status\n - Sortable and filterable\n - Enable/disable toggle per rule\n - Edit/Delete actions\n\n2. Add Rule Dialog\n - Rule type: Bandwidth Limit, Priority, Guarantee\n - Match criteria:\n * Source IP/MAC/Subnet\n * Destination IP/Subnet\n * Port/Service (HTTP, HTTPS, SSH, etc.)\n * Protocol (TCP, UDP, ICMP)\n * Application (DPI-based, if available)\n - Action:\n * Set download limit (kbps/mbps)\n * Set upload limit\n * Set priority (1-7, or class names)\n * Guarantee minimum bandwidth\n - Schedule (always, time-based, day-of-week)\n\nQUOTAS TAB:\n1. Bandwidth Quotas\n - Per-device quotas\n - Per-user quotas\n - Family quotas (group of devices)\n - Time-based quotas (daily, weekly, monthly)\n\n2. Quota Configuration\n - Set quota amount (GB)\n - Set quota period (day/week/month)\n - Action on quota exceeded:\n * Block all traffic\n * Throttle to X kbps\n * Send notification only\n - Quota reset schedule\n - Rollover unused quota (optional)\n\n3. Quota Usage Dashboard\n - Cards per device/user showing:\n * Quota limit\n * Used amount\n * Remaining\n * Progress bar with color coding\n * Reset date\n - Warning threshold (notify at 80%, 90%)\n\nUSAGE TAB:\n1. Historical Usage\n - Charts:\n * Daily usage (last 30 days) as bar chart\n * Hourly usage (last 24h) as line chart\n * Weekly usage (last 12 weeks) as area chart\n - Filter by device, service, direction (up/down)\n - Export to CSV\n\n2. Usage Statistics\n - Total transferred this month\n - Average daily usage\n - Peak hour (when usage is highest)\n - Trending applications\n\nMEDIA TAB:\n1. Media Traffic Detection\n - Streaming services: Netflix, YouTube, Disney+, Twitch, etc.\n - VoIP: Zoom, Teams, Discord, WhatsApp calls\n - Gaming: Steam, PlayStation, Xbox Live\n - Social Media: Facebook, Instagram, TikTok\n\n2. Media-Specific Rules\n - Quick templates:\n * Prioritize VoIP over streaming\n * Throttle streaming during work hours\n * Limit gaming bandwidth\n - Per-service bandwidth allocation\n - Quality-based throttling (4K vs 720p detection)\n\nCLASSES TAB:\n1. Traffic Classes (HTB/CAKE)\n - Predefined classes:\n * Realtime (VoIP, gaming): highest priority\n * Interactive (web browsing, SSH): high priority\n * Bulk (downloads, updates): low priority\n * Default: medium priority\n\n2. Class Configuration\n - Per-class bandwidth allocation (percentage or absolute)\n - Borrowing (allow class to use unused bandwidth from others)\n - Ceiling (maximum bandwidth a class can use)\n - Quantum (packet size for fair queuing)\n\nCLIENTS TAB:\n1. Per-Client Management\n - Client list with current bandwidth usage\n - Quick actions:\n * Set bandwidth limit for client\n * Apply quota to client\n * Block client temporarily\n * Assign to traffic class\n\nSCHEDULES TAB:\n1. Schedule Management\n - Create time-based rules\n - Examples:\n * Business hours (9am-5pm Mon-Fri): prioritize business apps\n * Evening (6pm-11pm): allow streaming\n * Late night (11pm-6am): throttle everything\n - Calendar view of schedules\n - Conflict detection\n\nSETTINGS TAB:\n1. Global Settings\n - WAN bandwidth limits (uplink/downlink in Mbps)\n - QoS algorithm: CAKE, HTB, SFQ, FQ_CODEL\n - Enable/disable QoS globally\n - Default traffic class\n - Bandwidth test (measure actual WAN speed)\n\n2. Advanced Settings\n - DSCP marking\n - ECN (Explicit Congestion Notification)\n - Overhead calculation (for PPPoE, etc.)\n - Per-packet overhead bytes\n - Link layer adaptation\n\nTECHNICAL:\n- RPCD: luci.bandwidth-manager\n- Methods: getStats, getRules, addRule, deleteRule, getQuotas, setQuota, getUsage\n- QoS implementation:\n * tc (traffic control) commands for HTB\n * cake qdisc for modern QoS\n * iptables conntrack for usage accounting\n * nftables meters for rate limiting\n- Database:\n * SQLite or UCI for rules and quotas\n * RRD for historical bandwidth data\n * iptables counters for real-time stats\n\nVISUAL ENHANCEMENTS:\n- Bandwidth gauge charts (animated)\n- Sparklines for trending\n- Color-coded quota bars\n- Responsive rule cards\n</code></pre>"},{"location":"feature-regeneration-prompts/#11-traffic-shaper-luci-app-traffic-shaper","title":"11. Traffic Shaper (luci-app-traffic-shaper)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create an advanced traffic shaping module with anti-bufferbloat (CAKE):\n\nDESIGN:\n- Title: \"Traffic Shaper\" with \ud83d\ude80 icon\n- Technical/advanced focus\n- Stats badges: Active Queues | Avg Latency | Packet Loss | Throughput\n\nOVERVIEW TAB:\n1. Shaper Status\n - QoS enabled status toggle\n - Active algorithm (CAKE, HTB, FQ_CODEL)\n - Shaped interfaces (WAN, LAN)\n - Current latency (ping to 1.1.1.1)\n\n2. Performance Metrics\n - Round-trip time (RTT) under load\n - Buffer size (current vs optimal)\n - Packet drop rate\n - Throughput (actual vs configured)\n\n3. Bufferbloat Test\n - Run DSLReports speed test button\n - Display results: download, upload, latency, grade\n - Historical test results chart\n\nCLASSES TAB:\n1. Traffic Classes (HTB hierarchy)\n - Root class (total bandwidth)\n - Child classes with priority:\n * Expedited Forwarding (EF): VoIP, gaming\n * Assured Forwarding (AF): business apps\n * Best Effort (BE): web, email\n * Background (bulk downloads)\n\n2. Class Configuration\n - Rate (guaranteed bandwidth)\n - Ceil (maximum bandwidth)\n - Priority (1-7)\n - Quantum (packet size)\n - Burst (allow temporary overage)\n\nRULES TAB:\n1. Classification Rules\n - Match criteria:\n * DSCP/TOS field\n * Port numbers\n * IP addresses\n * Protocol\n * DPI signature\n - Action: assign to traffic class\n - Rule priority (1-999)\n\n2. Rule Templates\n - Predefined rules:\n * VoIP optimization (SIP, RTP ports)\n * Gaming optimization (known game servers)\n * Streaming deprioritization\n * P2P throttling\n - One-click apply\n\nSTATS TAB:\n1. Queue Statistics\n - Per-class metrics:\n * Packets sent\n * Bytes sent\n * Drops (overload indicator)\n * Overlimits (ceiling hits)\n * Requeues\n - Real-time and historical charts\n\n2. Interface Statistics\n - Per-interface counters\n - Queue depth graphs\n - Latency measurements (ICMP ping or timestamping)\n\nPRESETS TAB:\n1. QoS Presets\n - Gaming preset (lowest latency, prioritize gaming ports)\n - Streaming preset (balance, allow bandwidth for streaming)\n - Business preset (prioritize VoIP, remote desktop)\n - Balanced preset (general home use)\n - Manual preset (custom configuration)\n\n2. Preset Configuration\n - Select preset from dropdown\n - Auto-configure all parameters\n - Show what will change (diff preview)\n - Apply button\n\nCAKE CONFIGURATION TAB:\n1. CAKE Settings\n - Bandwidth (uplink/downlink in Mbps)\n - Overhead:\n * None\n * ADSL (with interleaving)\n * VDSL2\n * Ethernet\n * PPPoE\n - Link layer adaptation:\n * Ethernet\n * ATM\n * PTM\n - Flows:\n * Triple-isolate (src IP, dst IP, port)\n * Dual-srchost\n * Dual-dsthost\n * Per-host\n - Diffserv:\n * Diffserv4 (4 tins)\n * Diffserv3 (3 tins)\n * Besteffort (single queue)\n - ECN: enable/disable\n - ACK filter: enable/disable (for slow uplinks)\n\nTECHNICAL:\n- RPCD: luci.traffic-shaper\n- Commands:\n * tc qdisc add/del/replace\n * tc class add/del/change\n * tc filter add/del\n * cake qdisc configuration\n- Real-time monitoring:\n * tc -s qdisc show\n * tc -s class show\n * Parse output for statistics\n- Latency testing:\n * ping command with timestamps\n * Integration with fping or hping3\n\nVISUAL ENHANCEMENTS:\n- Real-time latency graph (live updating)\n- Packet drop rate sparklines\n- Class hierarchy tree view\n- Color-coded classes by priority\n</code></pre>"},{"location":"feature-regeneration-prompts/#12-media-flow-luci-app-media-flow","title":"12. Media Flow (luci-app-media-flow)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a media streaming and VoIP traffic detection dashboard:\n\nDESIGN:\n- Title: \"Media Monitor\" with \ud83c\udfac icon\n- Focus on streaming services and video calls\n- Stats badges: Active Streams | VoIP Calls | Bandwidth Used | Services\n\nDASHBOARD TAB:\n1. Active Media Streams\n - Cards for each active stream:\n * Service logo (Netflix, YouTube, etc.)\n * Client device (IP, hostname)\n * Stream quality estimate (4K, 1080p, 720p, SD)\n * Current bitrate (Mbps)\n * Duration\n - Color-coded by service type (streaming=red, VoIP=green)\n\n2. Service Breakdown\n - Pie chart: bandwidth by service\n - Services:\n * Netflix, Amazon Prime, Disney+, Hulu, HBO Max\n * YouTube, Twitch, Vimeo\n * Spotify, Apple Music, Pandora\n * Zoom, Teams, Meet, Webex\n * WhatsApp, Telegram, FaceTime\n\nSERVICES TAB:\n1. Streaming Services Grid\n - Each service as card:\n * Icon/logo\n * Total bandwidth used today\n * Active sessions\n * Peak quality detected\n * Average session duration\n - Click card for details\n\n2. Service History\n - Per-service usage over time\n - Quality distribution (how often 4K vs HD vs SD)\n - Peak viewing hours\n\nCLIENTS TAB:\n1. Device Media Usage\n - Table: Device, Service, Quality, Bitrate, Duration\n - Group by device\n - Show total media consumption per device\n - Identify heavy streaming users\n\nHISTORY TAB:\n1. Historical Media Activity\n - Timeline view of all media sessions\n - Filter by: date range, service, device, quality\n - Export to CSV\n - Charts:\n * Daily streaming hours\n * Service popularity trends\n * Quality vs bandwidth correlation\n\nALERTS TAB:\n1. Media Alerts\n - Excessive streaming alerts\n - Quality degradation alerts (4K dropped to 720p)\n - VoIP quality issues (packet loss, jitter)\n - New service detection\n - Unusual patterns (e.g., streaming at 3am)\n\n2. Alert Configuration\n - Set thresholds for alerts\n - Notification methods (web UI, email, webhook)\n - Per-device alert rules\n\nTECHNICAL:\n- RPCD: luci.media-flow\n- DPI integration:\n * Netifyd for application detection\n * nDPI library for deep inspection\n * Signature matching for streaming protocols\n- Quality estimation:\n * Bitrate analysis (e.g., >15 Mbps = 4K, 5-15 Mbps = 1080p)\n * DASH/HLS manifest parsing (if accessible)\n- VoIP detection:\n * RTP/RTCP ports and patterns\n * SIP signaling detection\n * WebRTC detection\n\nSTREAMING PROTOCOLS:\n- HLS (HTTP Live Streaming)\n- DASH (Dynamic Adaptive Streaming)\n- RTMP (Real-Time Messaging Protocol)\n- RTP (for VoIP)\n- WebRTC (for video calls)\n</code></pre>"},{"location":"feature-regeneration-prompts/#performance-services-modules","title":"Performance & Services Modules","text":""},{"location":"feature-regeneration-prompts/#13-cdn-cache-luci-app-cdn-cache","title":"13. CDN Cache (luci-app-cdn-cache)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a CDN caching proxy dashboard with bandwidth savings analytics:\n\nDESIGN:\n- Title: \"CDN Cache\" with \ud83d\udca8 icon\n- Focus on performance and savings\n- Stats badges: Cache Hit Rate | Bandwidth Saved | Cached Objects | Storage Used\n\nOVERVIEW TAB:\n1. Cache Performance\n - Hit rate percentage (big gauge chart)\n - Requests today: total, hits, misses\n - Bandwidth saved estimate (GB and percentage)\n - Storage usage (used/total)\n\n2. Top Cached Content\n - Table: URL/domain, Hits, Size, Last Access\n - Content types breakdown (images, videos, scripts, docs)\n - Pie chart: cached vs non-cacheable traffic\n\nCACHE TAB:\n1. Cached Objects Browser\n - List of cached objects:\n * URL\n * Content-Type\n * Size\n * Expiry\n * Hit count\n * Actions (view, purge)\n - Search and filter\n - Bulk purge by pattern\n\n2. Cache Statistics\n - Total objects\n - Average object size\n - Largest objects\n - Most hit objects\n - Expiring soon count\n\nPOLICIES TAB:\n1. Caching Policies\n - Domains to cache (whitelist)\n - Domains to never cache (blacklist)\n - Content types to cache (image/*, video/*, text/css, etc.)\n - Max object size (MB)\n - Cache duration (TTL) by content type\n\n2. Cache Rules\n - Rule editor:\n * Match URL pattern (regex)\n * Cache duration override\n * Cache or bypass decision\n * Priority (1-100)\n\nSTATISTICS TAB:\n1. Performance Metrics\n - Response time comparison: cache hit vs miss\n - Bandwidth charts: cached vs origin\n - Request rate over time\n - Cache efficiency trends (24h, 7d, 30d)\n\n2. Savings Calculator\n - Original bandwidth used (without cache)\n - Bandwidth saved (GB)\n - Cost savings estimate ($ per GB from ISP)\n - Response time improvement (ms)\n\nMAINTENANCE TAB:\n1. Cache Maintenance\n - Purge all button (with confirmation)\n - Purge by pattern (e.g., *.youtube.com/*)\n - Purge expired objects\n - Optimize database (rebuild indexes)\n - Prewarm cache (prefetch popular URLs)\n\n2. Storage Management\n - Storage usage breakdown\n - LRU eviction settings (least recently used)\n - Max cache size configuration\n - Storage location (disk, RAM, or hybrid)\n\nSETTINGS TAB:\n1. CDN Cache Configuration\n - Enable/disable cache\n - Upstream DNS servers\n - Proxy port (transparent or explicit)\n - SSL certificate handling (bump or pass-through)\n - Logging level\n\n2. Advanced Settings\n - Negative caching (cache 404s, etc.)\n - Range request handling\n - Vary header support\n - ETag validation\n - Stale-while-revalidate\n\nTECHNICAL:\n- RPCD: luci.cdn-cache\n- Caching software:\n * Squid proxy\n * Nginx caching proxy\n * Varnish\n * OpenWrt's own uhttpd with caching module\n- Methods: getStats, getCacheObjects, purge, setPolicies\n- Storage backend: filesystem or database\n- Monitoring: access logs parsing for hit/miss\n\nVISUAL ENHANCEMENTS:\n- Animated gauge for hit rate\n- Sparklines for trending metrics\n- Color-coded savings (green = high savings)\n- Before/after comparison charts\n</code></pre>"},{"location":"feature-regeneration-prompts/#14-vhost-manager-luci-app-vhost-manager","title":"14. VHost Manager (luci-app-vhost-manager)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a virtual host and reverse proxy manager with auto SSL:\n\nDESIGN:\n- Title: \"Virtual Hosts\" with \ud83c\udf0d icon\n- Focus on web hosting and proxying\n- Stats badges: Active VHosts | SSL Certs | Total Requests | Uptime\n\nOVERVIEW TAB:\n1. VHost Summary\n - Total virtual hosts configured\n - Active (enabled) vs inactive\n - SSL-enabled hosts count\n - Certificate expiry warnings\n\n2. Quick Actions\n - Add VHost button\n - Request SSL Certificate button\n - View Access Logs button\n\nVHOSTS TAB:\n1. Virtual Hosts List\n - Cards for each vhost:\n * Domain name\n * Type (reverse proxy, static site, redirect)\n * Backend (if proxy)\n * Status (enabled/disabled)\n * SSL status (valid, expiring, none)\n * Actions (edit, disable, delete, view logs)\n\n2. Add/Edit VHost Dialog\n - Domain name input (auto-validate DNS)\n - VHost type:\n * Reverse Proxy (proxy to backend server)\n * Static Site (serve from directory)\n * Redirect (301/302 to another URL)\n - Backend configuration (for proxy):\n * Backend URL (http://192.168.1.10:8080)\n * Protocol (HTTP, HTTPS, WebSocket)\n * Load balancing (if multiple backends)\n - SSL configuration:\n * Auto (Let's Encrypt via ACME)\n * Manual (upload cert + key)\n * None (HTTP only)\n - Advanced:\n * Custom headers\n * Access control (allow/deny IPs)\n * Request rewriting\n\nINTERNAL TAB:\n1. Internal Services\n - Predefined proxies for common services:\n * LuCI itself\n * Netdata\n * CrowdSec dashboard\n * RustDesk\n * Custom apps\n - One-click enable proxy for internal service\n\nCERTIFICATES TAB:\n1. SSL Certificate Management\n - List of certificates:\n * Domain\n * Issuer (Let's Encrypt, self-signed, CA)\n * Valid From - Valid To\n * Days until expiry\n * Actions (renew, revoke, download, delete)\n\n2. ACME Configuration\n - ACME provider (Let's Encrypt production/staging, ZeroSSL, BuyPass)\n - Email for notifications\n - Challenge type:\n * HTTP-01 (port 80 validation)\n * DNS-01 (TXT record validation)\n * TLS-ALPN-01 (port 443 validation)\n - Auto-renewal toggle (renew when <30 days remaining)\n\n3. Request Certificate\n - Domain input (supports wildcards with DNS-01)\n - Validation method selector\n - Issue button (shows progress)\n\nSSL TAB:\n1. SSL/TLS Settings\n - Global SSL settings:\n * Minimum TLS version (1.0, 1.1, 1.2, 1.3)\n * Cipher suites\n * HSTS (HTTP Strict Transport Security)\n * OCSP stapling\n - Per-vhost overrides\n\nREDIRECTS TAB:\n1. Redirect Rules\n - Simple redirects:\n * From domain/path\n * To URL\n * Type (301 permanent, 302 temporary, 307 temporary preserve method)\n - Wildcard redirects\n - Regex-based redirects\n\nLOGS TAB:\n1. Access Logs\n - Combined access log for all vhosts\n - Filter by vhost, IP, status code, date\n - Columns: Timestamp, IP, Method, Path, Status, Bytes, Referrer, User-Agent\n - Real-time log streaming\n - Export to CSV\n\n2. Error Logs\n - Proxy errors (backend unreachable, timeout)\n - SSL errors (cert invalid, expired)\n - Configuration errors\n\nTECHNICAL:\n- RPCD: luci.vhost-manager\n- Reverse proxy software:\n * Nginx\n * HAProxy\n * Caddy (for auto SSL)\n * Apache\n- ACME client:\n * acme.sh script\n * Certbot\n * Caddy built-in ACME\n- Methods: getVHosts, addVHost, deleteVHost, requestCertificate, getLogs\n\nINTEGRATION:\n- DNS validation via API (Cloudflare, etc.)\n- Dynamic DNS updates\n- Firewall port opening (80, 443)\n- Let's Encrypt rate limit handling\n</code></pre>"},{"location":"feature-regeneration-prompts/#15-ksm-manager-luci-app-ksm-manager","title":"15. KSM Manager (luci-app-ksm-manager)","text":"<p>Prompt for Claude.ai:</p> <pre><code>Create a cryptographic key and secrets management dashboard with HSM support:\n\nDESIGN:\n- Title: \"Key Management\" with \ud83d\udd10 icon\n- Security-focused, professional aesthetic\n- Stats badges: Total Keys | Active Keys | Certificates | Secrets\n\nOVERVIEW TAB:\n1. Key Management Status\n - Total keys managed\n - Key types breakdown (RSA, ECDSA, ED25519)\n - Expiring keys (next 30 days)\n - HSM status (if connected)\n\n2. Recent Activity\n - Last key operations: generated, used, rotated, revoked\n - Audit log (last 20 entries)\n\nKEYS TAB:\n1. Cryptographic Keys List\n - Table: Key ID, Type, Size, Usage, Created, Expires, Status\n - Key types:\n * Signing keys (for code, documents)\n * Encryption keys (for data at rest)\n * Authentication keys (SSH, TLS client)\n - Actions: view, export public, rotate, revoke, delete\n\n2. Generate Key Dialog\n - Algorithm selection:\n * RSA (2048, 3072, 4096 bit)\n * ECDSA (P-256, P-384, P-521)\n * ED25519\n - Usage flags:\n * Digital signature\n * Key encipherment\n * Data encipherment\n - Storage:\n * Software (filesystem)\n * HSM (if available)\n * TPM (if available)\n - Passphrase protection (optional)\n\nHSM TAB:\n1. Hardware Security Module\n - HSM connection status\n - HSM info: vendor, model, firmware version\n - Available key slots\n - HSM operations:\n * Initialize HSM\n * Generate key on HSM\n * Import key to HSM\n * Backup HSM\n\nCERTIFICATES TAB:\n1. X.509 Certificate Management\n - List: Subject, Issuer, Valid From/To, Serial, Fingerprint\n - Certificate chain view\n - Actions: view details, export (PEM/DER), revoke\n\n2. Certificate Request (CSR)\n - Generate CSR for signing by CA\n - Fields: CN, O, OU, C, ST, L, Email\n - Key usage extensions\n - Export CSR for submission to CA\n\n3. Self-Signed Certificates\n - Quick generate self-signed cert\n - Validity period selection\n - Subject alternative names (SANs)\n\nSECRETS TAB:\n1. Secret Storage (Vault)\n - Key-value secret store\n - Secrets list: Name, Type, Created, Last Accessed\n - Secret types:\n * Password\n * API key\n * Token\n * Connection string\n - Encrypted at rest\n - Access control (which users/apps can access)\n\n2. Add Secret Dialog\n - Secret name (path-based: db/prod/password)\n - Secret value (masked input)\n - TTL (time-to-live, auto-expire)\n - Version control (keep old versions)\n\nSSH TAB:\n1. SSH Key Management\n - SSH key pairs list\n - Generate SSH key (RSA, ED25519, ECDSA)\n - Import existing key\n - Export public key (for authorized_keys)\n - Authorized keys management (who can SSH in)\n\nAUDIT TAB:\n1. Audit Log\n - All key operations logged:\n * Generated, imported, exported, used, rotated, revoked, deleted\n - Timestamp, user, operation, key ID, result\n - Filter by: date range, operation type, key ID, user\n - Export audit log\n\nSETTINGS TAB:\n1. KSM Configuration\n - Key storage location\n - Default key algorithm and size\n - Auto-rotation policy (rotate keys every X days)\n - Backup location and schedule\n - HSM connection settings (if supported)\n\nTECHNICAL:\n- RPCD: luci.ksm-manager\n- Key storage:\n * OpenSSL for key operations\n * GnuPG for PGP keys\n * SSH-keygen for SSH keys\n * HSM integration via PKCS#11\n- Secret encryption:\n * Encrypt secrets with master key\n * Master key derived from passphrase or stored in HSM\n- Methods: listKeys, generateKey, exportKey, importKey, listSecrets, addSecret, getSecret\n\nSECURITY:\n- All secrets encrypted at rest\n- Audit logging of all operations\n- Access control (role-based)\n- Secure key deletion (overwrite before delete)\n</code></pre>"},{"location":"feature-regeneration-prompts/#common-ui-patterns-across-all-modules","title":"Common UI Patterns Across All Modules","text":""},{"location":"feature-regeneration-prompts/#global-design-consistency","title":"Global Design Consistency","text":"<p>All modules MUST include:</p> <ol> <li> <p>Page Header Pattern <pre><code>E('div', { 'class': 'sh-page-header' }, [\n E('div', {}, [\n E('h2', { 'class': 'sh-page-title' }, [\n E('span', { 'class': 'sh-page-title-icon' }, '[ICON]'),\n '[MODULE TITLE]'\n ]),\n E('p', { 'class': 'sh-page-subtitle' }, '[DESCRIPTION]')\n ]),\n E('div', { 'class': 'sh-stats-grid' }, [\n // 4 stat badges minimum\n ])\n])\n</code></pre></p> </li> <li> <p>Stats Badges (130px minimum, monospace values) <pre><code>E('div', { 'class': 'sh-stat-badge' }, [\n E('div', { 'class': 'sh-stat-value' }, '[VALUE]'),\n E('div', { 'class': 'sh-stat-label' }, '[LABEL]')\n])\n</code></pre></p> </li> <li> <p>Filter Tabs (for categorization) <pre><code>E('div', { 'class': 'sh-filter-tabs' }, [\n E('div', { 'class': 'sh-filter-tab active', 'data-filter': 'all' }, [\n E('span', { 'class': 'sh-tab-icon' }, '[ICON]'),\n E('span', { 'class': 'sh-tab-label' }, '[LABEL]')\n ])\n])\n</code></pre></p> </li> <li> <p>Cards with Color Borders <pre><code>E('div', { 'class': 'sh-card sh-card-success' }, [\n E('div', { 'class': 'sh-card-header' }, [\n E('h3', { 'class': 'sh-card-title' }, '[TITLE]')\n ]),\n E('div', { 'class': 'sh-card-body' }, [\n // Content\n ])\n])\n</code></pre></p> </li> <li> <p>Gradient Buttons <pre><code>E('button', { 'class': 'sh-btn sh-btn-primary' }, '[ACTION]')\n</code></pre></p> </li> <li> <p>Loading States</p> </li> <li>Skeleton screens while fetching data</li> <li>Spinner for button actions</li> <li> <p>Progress bars for long operations</p> </li> <li> <p>Error Handling</p> </li> <li>User-friendly error messages</li> <li>Retry buttons</li> <li> <p>Fallback content</p> </li> <li> <p>Responsive Design</p> </li> <li>Mobile-first approach</li> <li>Cards stack on mobile</li> <li>Stats grid adapts (130px minimum)</li> <li>Tables become scrollable or card-based</li> </ol>"},{"location":"feature-regeneration-prompts/#how-to-use-these-prompts","title":"How to Use These Prompts","text":""},{"location":"feature-regeneration-prompts/#step-1-select-module","title":"Step 1: Select Module","text":"<p>Choose the module you want to regenerate/implement from the list above.</p>"},{"location":"feature-regeneration-prompts/#step-2-copy-full-prompt","title":"Step 2: Copy Full Prompt","text":"<p>Copy the entire prompt for that module (from \"Create a...\" to \"VISUAL ENHANCEMENTS:\").</p>"},{"location":"feature-regeneration-prompts/#step-3-provide-to-claudeai","title":"Step 3: Provide to Claude.ai","text":"<p>Paste the prompt into Claude.ai (claude.ai conversation) with additional context:</p> <pre><code>I need you to implement [MODULE NAME] for OpenWrt LuCI.\n\nIMPORTANT CONSTRAINTS:\n- OpenWrt uses LuCI framework (not React/Vue)\n- JavaScript uses L.view pattern (not ES6 modules)\n- Backend is RPCD (shell scripts) communicating via ubus\n- CSS must use variables from common.css\n- All code must be production-ready\n- Follow the design system exactly\n\nHere's the complete specification:\n\n[PASTE PROMPT HERE]\n\nPlease provide:\n1. Complete JavaScript view file\n2. RPCD backend script\n3. Any required CSS\n4. ACL configuration\n5. Menu configuration JSON\n\nMake sure all code matches the live demo at secubox.cybermood.eu\n</code></pre>"},{"location":"feature-regeneration-prompts/#step-4-iterate","title":"Step 4: Iterate","text":"<p>If needed, provide screenshots from the live demo or request refinements to match the exact look and feel.</p>"},{"location":"feature-regeneration-prompts/#additional-resources","title":"Additional Resources","text":"<ul> <li>Live Demo: https://secubox.cybermood.eu</li> <li>Design System: DEVELOPMENT-GUIDELINES.md</li> <li>Quick Start: QUICK-START.md</li> <li>Build Guide: CLAUDE.md</li> </ul> <p>Document Version: 1.0.0 Last Updated: 2025-12-27 Maintainer: CyberMind.fr</p>"},{"location":"luci-development-reference/","title":"LuCI Development Reference Guide","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p> <p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active Based on: luci-app-secubox and luci-app-system-hub implementations Target Audience: Claude.ai and developers working on OpenWrt LuCI applications</p>"},{"location":"luci-development-reference/#see-also","title":"See Also","text":"<ul> <li>Design & Standards: DEVELOPMENT-GUIDELINES.md</li> <li>Quick Commands: QUICK-START.md</li> <li>Automation Briefing: CODEX.md</li> <li>Code Templates: CODE-TEMPLATES.md</li> </ul> <p>This document captures critical patterns, best practices, and common pitfalls discovered during the development of SecuBox LuCI applications. Use this as a validation reference for all future LuCI application development.</p>"},{"location":"luci-development-reference/#table-of-contents","title":"Table of Contents","text":"<ol> <li>ubus and RPC Fundamentals</li> <li>RPCD Backend Patterns</li> <li>LuCI API Module Patterns</li> <li>LuCI View Import Patterns</li> <li>ACL Permission Structure</li> <li>Data Structure Conventions</li> <li>Common Errors and Solutions</li> <li>Validation Checklist</li> <li>Testing and Deployment</li> </ol>"},{"location":"luci-development-reference/#ubus-and-rpc-fundamentals","title":"ubus and RPC Fundamentals","text":""},{"location":"luci-development-reference/#what-is-ubus","title":"What is ubus?","text":"<p>ubus (OpenWrt micro bus architecture) is OpenWrt's inter-process communication (IPC) system. It enables: - RPC (Remote Procedure Call) between processes - Web interface (LuCI) to backend service communication - Command-line interaction via <code>ubus call</code></p>"},{"location":"luci-development-reference/#ubus-object-naming-convention","title":"ubus Object Naming Convention","text":"<p>CRITICAL RULE: All LuCI application ubus objects MUST use the <code>luci.</code> prefix.</p> <pre><code>// \u2705 CORRECT\nobject: 'luci.system-hub'\nobject: 'luci.cdn-cache'\nobject: 'luci.wireguard-dashboard'\n\n// \u274c WRONG\nobject: 'system-hub'\nobject: 'systemhub'\nobject: 'cdn-cache'\n</code></pre> <p>Why? LuCI expects objects under the <code>luci.*</code> namespace for web applications. Without this prefix: - ACL permissions won't match - RPCD won't route calls correctly - Browser console shows: <code>RPC call to system-hub/status failed with error -32000: Object not found</code></p>"},{"location":"luci-development-reference/#rpcd-script-naming-must-match-ubus-object","title":"RPCD Script Naming MUST Match ubus Object","text":"<p>The RPCD script filename MUST exactly match the ubus object name:</p> <pre><code># If JavaScript declares:\n# object: 'luci.system-hub'\n\n# Then RPCD script MUST be named:\n/usr/libexec/rpcd/luci.system-hub\n\n# NOT:\n/usr/libexec/rpcd/system-hub\n/usr/libexec/rpcd/luci-system-hub\n</code></pre> <p>Validation Command: <pre><code># Check JavaScript files for ubus object names\ngrep -r \"object:\" luci-app-*/htdocs --include=\"*.js\"\n\n# Verify RPCD script exists with matching name\nls luci-app-*/root/usr/libexec/rpcd/\n</code></pre></p>"},{"location":"luci-development-reference/#ubus-call-types","title":"ubus Call Types","text":"<p>Read Operations (GET-like): - <code>status</code> - Get current state - <code>get_*</code> - Retrieve data (e.g., <code>get_health</code>, <code>get_settings</code>) - <code>list_*</code> - Enumerate items (e.g., <code>list_services</code>)</p> <p>Write Operations (POST-like): - <code>save_*</code> - Persist configuration (e.g., <code>save_settings</code>) - <code>*_action</code> - Perform actions (e.g., <code>service_action</code>) - <code>backup</code>, <code>restore</code>, <code>reboot</code> - System modifications</p> <p>ACL Mapping: - Read operations \u2192 <code>\"read\"</code> section in ACL - Write operations \u2192 <code>\"write\"</code> section in ACL</p>"},{"location":"luci-development-reference/#rpcd-backend-patterns","title":"RPCD Backend Patterns","text":""},{"location":"luci-development-reference/#shell-script-structure","title":"Shell Script Structure","text":"<p>RPCD backends are executable shell scripts that: 1. Parse <code>$1</code> for the action (<code>list</code> or <code>call</code>) 2. Parse <code>$2</code> for the method name (if <code>call</code>) 3. Read JSON input from stdin (for methods with parameters) 4. Output JSON to stdout 5. Exit with status 0 on success, non-zero on error</p>"},{"location":"luci-development-reference/#standard-template","title":"Standard Template","text":"<pre><code>#!/bin/sh\n# RPCD Backend: luci.system-hub\n# Version: 0.1.0\n\n# Source JSON shell helper\n. /usr/share/libubox/jshn.sh\n\ncase \"$1\" in\n list)\n # List all available methods and their parameters\n echo '{\n \"status\": {},\n \"get_health\": {},\n \"service_action\": { \"service\": \"string\", \"action\": \"string\" },\n \"save_settings\": {\n \"auto_refresh\": 0,\n \"health_check\": 0,\n \"refresh_interval\": 0\n }\n }'\n ;;\n call)\n case \"$2\" in\n status)\n status\n ;;\n get_health)\n get_health\n ;;\n service_action)\n # Read JSON input from stdin\n read -r input\n json_load \"$input\"\n json_get_var service service\n json_get_var action action\n service_action \"$service\" \"$action\"\n ;;\n save_settings)\n read -r input\n json_load \"$input\"\n json_get_var auto_refresh auto_refresh\n json_get_var health_check health_check\n json_get_var refresh_interval refresh_interval\n save_settings \"$auto_refresh\" \"$health_check\" \"$refresh_interval\"\n ;;\n *)\n echo '{\"error\": \"Method not found\"}'\n exit 1\n ;;\n esac\n ;;\nesac\n</code></pre>"},{"location":"luci-development-reference/#json-output-with-jshnsh","title":"JSON Output with jshn.sh","text":"<p>jshn.sh provides shell functions for JSON manipulation:</p> <pre><code># Initialize JSON object\njson_init\n\n# Add simple values\njson_add_string \"hostname\" \"openwrt\"\njson_add_int \"uptime\" 86400\njson_add_boolean \"running\" 1\n\n# Add nested object\njson_add_object \"cpu\"\njson_add_int \"usage\" 25\njson_add_string \"status\" \"ok\"\njson_close_object\n\n# Add array\njson_add_array \"services\"\njson_add_string \"\" \"network\"\njson_add_string \"\" \"firewall\"\njson_close_array\n\n# Output JSON to stdout\njson_dump\n</code></pre> <p>Common Functions: - <code>json_init</code> - Start new JSON object - <code>json_add_string \"key\" \"value\"</code> - Add string - <code>json_add_int \"key\" 123</code> - Add integer - <code>json_add_boolean \"key\" 1</code> - Add boolean (0 or 1) - <code>json_add_object \"key\"</code> - Start nested object - <code>json_close_object</code> - End nested object - <code>json_add_array \"key\"</code> - Start array - <code>json_close_array</code> - End array - <code>json_dump</code> - Output JSON to stdout</p>"},{"location":"luci-development-reference/#error-handling","title":"Error Handling","text":"<p>Always validate inputs and return meaningful errors:</p> <pre><code>service_action() {\n local service=\"$1\"\n local action=\"$2\"\n\n # Validate service name\n if [ -z \"$service\" ]; then\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"error\" \"Service name is required\"\n json_dump\n return 1\n fi\n\n # Validate action\n case \"$action\" in\n start|stop|restart|enable|disable)\n ;;\n *)\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"error\" \"Invalid action: $action\"\n json_dump\n return 1\n ;;\n esac\n\n # Perform action\n /etc/init.d/\"$service\" \"$action\" >/dev/null 2>&1\n\n if [ $? -eq 0 ]; then\n json_init\n json_add_boolean \"success\" 1\n json_add_string \"message\" \"Service $service $action successful\"\n json_dump\n else\n json_init\n json_add_boolean \"success\" 0\n json_add_string \"error\" \"Service $service $action failed\"\n json_dump\n return 1\n fi\n}\n</code></pre>"},{"location":"luci-development-reference/#uci-integration","title":"UCI Integration","text":"<p>For persistent configuration, use UCI (Unified Configuration Interface):</p> <pre><code>save_settings() {\n local auto_refresh=\"$1\"\n local health_check=\"$2\"\n local refresh_interval=\"$3\"\n\n # Create/update UCI config\n uci set system-hub.general=general\n uci set system-hub.general.auto_refresh=\"$auto_refresh\"\n uci set system-hub.general.health_check=\"$health_check\"\n uci set system-hub.general.refresh_interval=\"$refresh_interval\"\n uci commit system-hub\n\n json_init\n json_add_boolean \"success\" 1\n json_add_string \"message\" \"Settings saved successfully\"\n json_dump\n}\n\nget_settings() {\n # Load UCI config\n if [ -f \"/etc/config/system-hub\" ]; then\n . /lib/functions.sh\n config_load system-hub\n fi\n\n json_init\n json_add_object \"general\"\n\n # Get value or use default\n config_get auto_refresh general auto_refresh \"1\"\n json_add_boolean \"auto_refresh\" \"${auto_refresh:-1}\"\n\n config_get refresh_interval general refresh_interval \"30\"\n json_add_int \"refresh_interval\" \"${refresh_interval:-30}\"\n\n json_close_object\n json_dump\n}\n</code></pre>"},{"location":"luci-development-reference/#performance-tips","title":"Performance Tips","text":"<ol> <li>Cache expensive operations: Don't re-read <code>/proc</code> files multiple times</li> <li>Use command substitution efficiently: <pre><code># Good\nuptime=$(cat /proc/uptime | cut -d' ' -f1)\n\n# Better\nread uptime _ < /proc/uptime\nuptime=${uptime%.*}\n</code></pre></li> <li>Avoid external commands when possible: <pre><code># Slow\ncount=$(ls /etc/init.d | wc -l)\n\n# Fast\ncount=0\nfor file in /etc/init.d/*; do\n [ -f \"$file\" ] && count=$((count + 1))\ndone\n</code></pre></li> </ol>"},{"location":"luci-development-reference/#luci-api-module-patterns","title":"LuCI API Module Patterns","text":""},{"location":"luci-development-reference/#critical-use-baseclassextend","title":"CRITICAL: Use baseclass.extend()","text":"<p>RULE: LuCI API modules MUST use <code>baseclass.extend()</code> pattern.</p> <pre><code>'use strict';\n'require baseclass';\n'require rpc';\n\n// Declare RPC methods\nvar callStatus = rpc.declare({\n object: 'luci.system-hub',\n method: 'status',\n expect: {}\n});\n\nvar callGetHealth = rpc.declare({\n object: 'luci.system-hub',\n method: 'get_health',\n expect: {}\n});\n\nvar callSaveSettings = rpc.declare({\n object: 'luci.system-hub',\n method: 'save_settings',\n params: ['auto_refresh', 'health_check', 'refresh_interval'],\n expect: {}\n});\n\n// \u2705 CORRECT: Use baseclass.extend()\nreturn baseclass.extend({\n getStatus: callStatus,\n getHealth: callGetHealth,\n saveSettings: callSaveSettings\n});\n\n// \u274c WRONG: Do NOT use these patterns\nreturn baseclass.singleton({...}); // Breaks everything!\nreturn {...}; // Plain object doesn't work\n</code></pre> <p>Why baseclass.extend()? - LuCI's module system expects class-based modules - Views import with <code>'require module/api as API'</code> which auto-instantiates - <code>baseclass.extend()</code> creates a proper class constructor - <code>baseclass.singleton()</code> breaks the instantiation mechanism - Plain objects don't support LuCI's module lifecycle</p>"},{"location":"luci-development-reference/#rpcdeclare-parameters","title":"rpc.declare() Parameters","text":"<pre><code>var callMethodName = rpc.declare({\n object: 'luci.module-name', // ubus object name (MUST start with luci.)\n method: 'method_name', // RPCD method name\n params: ['param1', 'param2'], // Optional: parameter names (order matters!)\n expect: {} // Expected return structure (or { key: [] } for arrays)\n});\n</code></pre> <p>Parameter Order Matters: <pre><code>// RPCD expects parameters in this exact order\nvar callSaveSettings = rpc.declare({\n object: 'luci.system-hub',\n method: 'save_settings',\n params: ['auto_refresh', 'health_check', 'debug_mode', 'refresh_interval'],\n expect: {}\n});\n\n// JavaScript call MUST pass parameters in same order\nAPI.saveSettings(1, 1, 0, 30); // auto_refresh=1, health_check=1, debug_mode=0, refresh_interval=30\n</code></pre></p>"},{"location":"luci-development-reference/#expect-parameter-patterns","title":"expect Parameter Patterns","text":"<pre><code>// Method returns single object\nexpect: {}\n\n// Method returns array at top level\nexpect: { services: [] }\n\n// Method returns specific structure\nexpect: {\n services: [],\n count: 0\n}\n</code></pre>"},{"location":"luci-development-reference/#error-handling-in-api-module","title":"Error Handling in API Module","text":"<p>API methods return Promises. Handle errors in views:</p> <pre><code>return API.getHealth().then(function(data) {\n if (!data || typeof data !== 'object') {\n console.error('Invalid health data:', data);\n return null;\n }\n return data;\n}).catch(function(err) {\n console.error('Failed to load health data:', err);\n ui.addNotification(null, E('p', {}, 'Failed to load health data'), 'error');\n return null;\n});\n</code></pre>"},{"location":"luci-development-reference/#luci-view-import-patterns","title":"LuCI View Import Patterns","text":""},{"location":"luci-development-reference/#critical-use-require-as-var-for-apis","title":"CRITICAL: Use 'require ... as VAR' for APIs","text":"<p>RULE: When importing API modules, use the <code>'require ... as VAR'</code> pattern at the top of the file.</p> <pre><code>// \u2705 CORRECT: Auto-instantiates the class\n'require system-hub/api as API';\n\nreturn L.view.extend({\n load: function() {\n return API.getHealth(); // API is already instantiated\n }\n});\n\n// \u274c WRONG: Returns class constructor, not instance\nvar api = L.require('system-hub.api');\napi.getHealth(); // ERROR: api.getHealth is not a function\n</code></pre> <p>Why? - <code>'require module/path as VAR'</code> (with forward slashes) auto-instantiates classes - <code>L.require('module.path')</code> (with dots) returns raw class constructor - API modules extend <code>baseclass</code>, which needs instantiation - LuCI's module loader handles instantiation when using the <code>as VAR</code> pattern</p>"},{"location":"luci-development-reference/#standard-view-structure","title":"Standard View Structure","text":"<pre><code>'use strict';\n'require view';\n'require form';\n'require ui';\n'require system-hub/api as API';\n\nreturn L.view.extend({\n load: function() {\n // Load data needed for rendering\n return Promise.all([\n API.getHealth(),\n API.getStatus()\n ]);\n },\n\n render: function(data) {\n var health = data[0];\n var status = data[1];\n\n // Create UI elements\n var container = E('div', { 'class': 'cbi-map' }, [\n E('h2', {}, 'Dashboard'),\n // ... more elements\n ]);\n\n return container;\n },\n\n handleSave: null, // Disable save button\n handleSaveApply: null, // Disable save & apply button\n handleReset: null // Disable reset button\n});\n</code></pre>"},{"location":"luci-development-reference/#import-patterns-summary","title":"Import Patterns Summary","text":"<pre><code>// Core LuCI modules (always with quotes)\n'require view';\n'require form';\n'require ui';\n'require rpc';\n'require baseclass';\n\n// Custom API modules (use 'as VAR' for auto-instantiation)\n'require system-hub/api as API';\n'require cdn-cache/api as CdnAPI';\n\n// Access global L object (no require)\nL.resolveDefault(...)\nL.Poll.add(...)\nL.ui.addNotification(...)\n</code></pre>"},{"location":"luci-development-reference/#acl-permission-structure","title":"ACL Permission Structure","text":""},{"location":"luci-development-reference/#file-location","title":"File Location","text":"<p>ACL files are located in: <pre><code>/usr/share/rpcd/acl.d/luci-app-<module-name>.json\n</code></pre></p> <p>In source tree: <pre><code>luci-app-<module-name>/root/usr/share/rpcd/acl.d/luci-app-<module-name>.json\n</code></pre></p>"},{"location":"luci-development-reference/#standard-acl-template","title":"Standard ACL Template","text":"<pre><code>{\n \"luci-app-module-name\": {\n \"description\": \"Module Name - Description\",\n \"read\": {\n \"ubus\": {\n \"luci.module-name\": [\n \"status\",\n \"get_system_info\",\n \"get_health\",\n \"list_services\",\n \"get_logs\",\n \"get_storage\",\n \"get_settings\"\n ]\n }\n },\n \"write\": {\n \"ubus\": {\n \"luci.module-name\": [\n \"service_action\",\n \"backup_config\",\n \"restore_config\",\n \"reboot\",\n \"save_settings\"\n ]\n }\n }\n }\n}\n</code></pre>"},{"location":"luci-development-reference/#read-vs-write-classification","title":"Read vs Write Classification","text":"<p>Read Operations (no system modification): - <code>status</code> - Get current state - <code>get_*</code> - Retrieve data (system info, health, settings, logs, storage) - <code>list_*</code> - Enumerate items (services, interfaces, etc.)</p> <p>Write Operations (modify system state): - <code>*_action</code> - Perform actions (start/stop services, etc.) - <code>save_*</code> - Persist configuration changes - <code>backup</code>, <code>restore</code> - System backup/restore - <code>reboot</code>, <code>shutdown</code> - System control</p>"},{"location":"luci-development-reference/#common-acl-errors","title":"Common ACL Errors","text":"<p>Error: <code>Access denied</code> or RPC error <code>-32002</code></p> <p>Cause: Method not listed in ACL, or listed in wrong section (read vs write)</p> <p>Solution: 1. Identify if method is read or write operation 2. Add method name to correct section in ACL 3. Restart RPCD: <code>/etc/init.d/rpcd restart</code></p> <p>Validation: <pre><code># Check if ACL file is valid JSON\njsonlint /usr/share/rpcd/acl.d/luci-app-system-hub.json\n\n# List all ubus objects and methods\nubus list luci.system-hub\n\n# Test method with ubus call\nubus call luci.system-hub get_health\n</code></pre></p>"},{"location":"luci-development-reference/#data-structure-conventions","title":"Data Structure Conventions","text":""},{"location":"luci-development-reference/#health-metrics-structure-system-hub-v010","title":"Health Metrics Structure (system-hub v0.1.0)","text":"<p>Based on extensive iteration, this structure provides clarity and consistency:</p> <pre><code>{\n \"cpu\": {\n \"usage\": 25,\n \"status\": \"ok\",\n \"load_1m\": \"0.25\",\n \"load_5m\": \"0.30\",\n \"load_15m\": \"0.28\",\n \"cores\": 4\n },\n \"memory\": {\n \"total_kb\": 4096000,\n \"free_kb\": 2048000,\n \"available_kb\": 3072000,\n \"used_kb\": 1024000,\n \"buffers_kb\": 512000,\n \"cached_kb\": 1536000,\n \"usage\": 25,\n \"status\": \"ok\"\n },\n \"disk\": {\n \"total_kb\": 30408704,\n \"used_kb\": 5447680,\n \"free_kb\": 24961024,\n \"usage\": 19,\n \"status\": \"ok\"\n },\n \"temperature\": {\n \"value\": 45,\n \"status\": \"ok\"\n },\n \"network\": {\n \"wan_up\": true,\n \"status\": \"ok\"\n },\n \"services\": {\n \"running\": 35,\n \"failed\": 2\n },\n \"score\": 92,\n \"timestamp\": \"2025-12-26 10:30:00\",\n \"recommendations\": [\n \"2 service(s) enabled but not running. Check service status.\"\n ]\n}\n</code></pre> <p>Key Principles: 1. Nested objects for related metrics (cpu, memory, disk, etc.) 2. Consistent structure: Each metric has <code>usage</code> (percentage) and <code>status</code> (ok/warning/critical) 3. Raw values + computed values: Provide both (e.g., <code>used_kb</code> AND <code>usage</code> percentage) 4. Status thresholds: ok (< warning), warning (warning-critical), critical (\u2265 critical) 5. Overall score: Single 0-100 health score for dashboard 6. Dynamic recommendations: Array of actionable alerts based on thresholds</p>"},{"location":"luci-development-reference/#status-values","title":"Status Values","text":"<p>Use consistent status strings across all metrics: - <code>\"ok\"</code> - Normal operation (green) - <code>\"warning\"</code> - Approaching threshold (orange) - <code>\"critical\"</code> - Exceeded threshold (red) - <code>\"error\"</code> - Unable to retrieve metric - <code>\"unknown\"</code> - Metric not available</p>"},{"location":"luci-development-reference/#timestamp-format","title":"Timestamp Format","text":"<p>Use ISO 8601 or consistent local format: <pre><code>timestamp=\"$(date '+%Y-%m-%d %H:%M:%S')\" # 2025-12-26 10:30:00\n</code></pre></p>"},{"location":"luci-development-reference/#boolean-values-in-json","title":"Boolean Values in JSON","text":"<p>In shell scripts using jshn.sh: <pre><code>json_add_boolean \"wan_up\" 1 # true\njson_add_boolean \"wan_up\" 0 # false\n</code></pre></p> <p>In JavaScript: <pre><code>if (health.network.wan_up) {\n // WAN is up\n}\n</code></pre></p>"},{"location":"luci-development-reference/#array-vs-single-value","title":"Array vs Single Value","text":"<p>Use arrays for: - Multiple items of same type (services, interfaces, mount points) - Variable-length data</p> <p>Use single values for: - System-wide metrics (CPU, memory, disk) - Primary/aggregate values (overall temperature, total uptime)</p> <p>Example - Storage: <pre><code>// Multiple mount points - use array\n\"storage\": [\n {\n \"mount\": \"/\",\n \"total_kb\": 30408704,\n \"used_kb\": 5447680,\n \"usage\": 19\n },\n {\n \"mount\": \"/mnt/usb\",\n \"total_kb\": 128000000,\n \"used_kb\": 64000000,\n \"usage\": 50\n }\n]\n\n// Root filesystem only - use object\n\"disk\": {\n \"total_kb\": 30408704,\n \"used_kb\": 5447680,\n \"usage\": 19,\n \"status\": \"ok\"\n}\n</code></pre></p>"},{"location":"luci-development-reference/#common-errors-and-solutions","title":"Common Errors and Solutions","text":""},{"location":"luci-development-reference/#1-rpc-error-object-not-found-32000","title":"1. RPC Error: \"Object not found\" (-32000)","text":"<p>Error Message: <pre><code>RPC call to system-hub/status failed with error -32000: Object not found\n</code></pre></p> <p>Cause: RPCD script name doesn't match ubus object name in JavaScript</p> <p>Solution: 1. Check JavaScript for object name: <pre><code>grep -r \"object:\" luci-app-system-hub/htdocs --include=\"*.js\"\n</code></pre> Output: <code>object: 'luci.system-hub'</code></p> <ol> <li> <p>Rename RPCD script to match exactly: <pre><code>mv root/usr/libexec/rpcd/system-hub root/usr/libexec/rpcd/luci.system-hub\n</code></pre></p> </li> <li> <p>Ensure script is executable: <pre><code>chmod +x root/usr/libexec/rpcd/luci.system-hub\n</code></pre></p> </li> <li> <p>Restart RPCD: <pre><code>/etc/init.d/rpcd restart\n</code></pre></p> </li> </ol>"},{"location":"luci-development-reference/#2-javascript-error-apimethodname-is-not-a-function","title":"2. JavaScript Error: \"api.methodName is not a function\"","text":"<p>Error Message: <pre><code>Uncaught TypeError: api.getHealth is not a function\n at view.load (health.js:12)\n</code></pre></p> <p>Cause: Wrong import pattern - imported class constructor instead of instance</p> <p>Solution: Change from: <pre><code>var api = L.require('system-hub.api'); // \u274c Wrong\n</code></pre></p> <p>To: <pre><code>'require system-hub/api as API'; // \u2705 Correct\n</code></pre></p> <p>Why: <code>L.require('module.path')</code> returns raw class, <code>'require module/path as VAR'</code> auto-instantiates.</p>"},{"location":"luci-development-reference/#3-rpc-error-access-denied-32002","title":"3. RPC Error: \"Access denied\" (-32002)","text":"<p>Error Message: <pre><code>RPC call to luci.system-hub/get_settings failed with error -32002: Access denied\n</code></pre></p> <p>Cause: Method not listed in ACL file, or in wrong section (read vs write)</p> <p>Solution: 1. Open ACL file: <code>root/usr/share/rpcd/acl.d/luci-app-system-hub.json</code></p> <ol> <li> <p>Add method to appropriate section: <pre><code>\"read\": {\n \"ubus\": {\n \"luci.system-hub\": [\n \"get_settings\"\n ]\n }\n}\n</code></pre></p> </li> <li> <p>Deploy and restart RPCD: <pre><code>scp luci-app-system-hub/root/usr/share/rpcd/acl.d/*.json router:/usr/share/rpcd/acl.d/\nssh router \"/etc/init.d/rpcd restart\"\n</code></pre></p> </li> </ol>"},{"location":"luci-development-reference/#4-display-error-nan-or-undefined-values","title":"4. Display Error: \"NaN%\" or Undefined Values","text":"<p>Error: Dashboard shows \"NaN%\", \"undefined\", or empty values</p> <p>Cause: Frontend using wrong data structure keys (outdated after backend changes)</p> <p>Solution: 1. Check backend output: <pre><code>ubus call luci.system-hub get_health\n</code></pre></p> <ol> <li> <p>Update frontend to match structure: <pre><code>// \u274c Old structure\nvar cpuPercent = health.load / health.cores * 100;\nvar memPercent = health.memory.percent;\n\n// \u2705 New structure\nvar cpuPercent = health.cpu ? health.cpu.usage : 0;\nvar memPercent = health.memory ? health.memory.usage : 0;\n</code></pre></p> </li> <li> <p>Add null/undefined checks: <pre><code>var temp = health.temperature?.value || 0;\nvar loadAvg = health.cpu?.load_1m || '0.00';\n</code></pre></p> </li> </ol>"},{"location":"luci-development-reference/#5-http-404-view-file-not-found","title":"5. HTTP 404: View File Not Found","text":"<p>Error Message: <pre><code>HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'\n</code></pre></p> <p>Cause: Menu path doesn't match actual view file location</p> <p>Solution: 1. Check menu JSON: <pre><code>cat root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json\n</code></pre> Look for: <code>\"path\": \"netifyd/overview\"</code></p> <ol> <li> <p>Check actual file location: <pre><code>ls htdocs/luci-static/resources/view/\n</code></pre> File is at: <code>view/netifyd-dashboard/overview.js</code></p> </li> <li> <p>Fix either menu path OR file location: <pre><code>// Option 1: Update menu path to match file\n\"path\": \"netifyd-dashboard/overview\"\n\n// Option 2: Move file to match menu\nmv view/netifyd-dashboard/ view/netifyd/\n</code></pre></p> </li> </ol>"},{"location":"luci-development-reference/#6-build-error-factory-yields-invalid-constructor","title":"6. Build Error: \"factory yields invalid constructor\"","text":"<p>Error Message: <pre><code>/luci-static/resources/system-hub/api.js: factory yields invalid constructor\n</code></pre></p> <p>Cause: Used wrong pattern in API module (singleton, plain object, etc.)</p> <p>Solution: Always use <code>baseclass.extend()</code>: <pre><code>return baseclass.extend({\n getStatus: callStatus,\n getHealth: callGetHealth,\n // ... more methods\n});\n</code></pre></p> <p>Do NOT use: - <code>baseclass.singleton({...})</code> - Plain object: <code>return {...}</code> - <code>baseclass.prototype</code></p>"},{"location":"luci-development-reference/#7-rpcd-not-responding-after-changes","title":"7. RPCD Not Responding After Changes","text":"<p>Symptom: Changes to RPCD script don't take effect</p> <p>Solution: 1. Verify script is deployed: <pre><code>ssh router \"ls -la /usr/libexec/rpcd/\"\n</code></pre></p> <ol> <li> <p>Check script is executable: <pre><code>ssh router \"chmod +x /usr/libexec/rpcd/luci.system-hub\"\n</code></pre></p> </li> <li> <p>Restart RPCD: <pre><code>ssh router \"/etc/init.d/rpcd restart\"\n</code></pre></p> </li> <li> <p>Clear browser cache (Ctrl+Shift+R)</p> </li> <li> <p>Check RPCD logs: <pre><code>ssh router \"logread | grep rpcd\"\n</code></pre></p> </li> </ol>"},{"location":"luci-development-reference/#validation-checklist","title":"Validation Checklist","text":"<p>Use this checklist before deployment:</p>"},{"location":"luci-development-reference/#file-structure","title":"File Structure","text":"<ul> <li> RPCD script exists: <code>/usr/libexec/rpcd/luci.<module-name></code></li> <li> RPCD script is executable: <code>chmod +x</code></li> <li> Menu JSON exists: <code>/usr/share/luci/menu.d/luci-app-<module>.json</code></li> <li> ACL JSON exists: <code>/usr/share/rpcd/acl.d/luci-app-<module>.json</code></li> <li> API module exists: <code>htdocs/luci-static/resources/<module>/api.js</code></li> <li> Views exist: <code>htdocs/luci-static/resources/view/<module>/*.js</code></li> </ul>"},{"location":"luci-development-reference/#naming-conventions","title":"Naming Conventions","text":"<ul> <li> RPCD script name matches ubus object in JavaScript (including <code>luci.</code> prefix)</li> <li> Menu paths match view file directory structure</li> <li> All ubus objects start with <code>luci.</code></li> <li> ACL key matches package name: <code>\"luci-app-<module>\"</code></li> </ul>"},{"location":"luci-development-reference/#code-validation","title":"Code Validation","text":"<ul> <li> API module uses <code>baseclass.extend()</code> pattern</li> <li> Views import API with <code>'require <module>/api as API'</code> pattern</li> <li> All rpc.declare() calls include correct <code>object</code>, <code>method</code>, <code>params</code>, <code>expect</code></li> <li> RPCD script outputs valid JSON (test with <code>ubus call</code>)</li> <li> Menu JSON is valid (test with <code>jsonlint</code>)</li> <li> ACL JSON is valid (test with <code>jsonlint</code>)</li> </ul>"},{"location":"luci-development-reference/#permissions","title":"Permissions","text":"<ul> <li> All read methods in ACL <code>\"read\"</code> section</li> <li> All write methods in ACL <code>\"write\"</code> section</li> <li> Methods in ACL match RPCD script method names exactly</li> </ul>"},{"location":"luci-development-reference/#testing","title":"Testing","text":"<ul> <li> Run validation script: <code>./secubox-tools/validate-modules.sh</code></li> <li> Test each method via ubus: <code>ubus call luci.<module> <method></code></li> <li> Test frontend in browser (check console for errors)</li> <li> Clear browser cache after deployment</li> <li> Verify RPCD restart: <code>/etc/init.d/rpcd restart</code></li> </ul>"},{"location":"luci-development-reference/#automated-validation-command","title":"Automated Validation Command","text":"<pre><code># Run comprehensive validation\n./secubox-tools/validate-modules.sh\n\n# Validate specific module\n./secubox-tools/validate-module-generation.sh luci-app-system-hub\n\n# Check JSON syntax\nfind luci-app-system-hub -name \"*.json\" -exec jsonlint {} \\;\n\n# Check shell scripts\nshellcheck luci-app-system-hub/root/usr/libexec/rpcd/*\n</code></pre>"},{"location":"luci-development-reference/#testing-and-deployment","title":"Testing and Deployment","text":""},{"location":"luci-development-reference/#local-testing-with-ubus","title":"Local Testing with ubus","text":"<p>Before deploying to router, test RPCD script locally:</p> <pre><code># Copy RPCD script to local /tmp\ncp luci-app-system-hub/root/usr/libexec/rpcd/luci.system-hub /tmp/\n\n# Make executable\nchmod +x /tmp/luci.system-hub\n\n# Test 'list' action\n/tmp/luci.system-hub list\n\n# Test 'call' action with method\n/tmp/luci.system-hub call status\n\n# Test method with parameters\necho '{\"service\":\"network\",\"action\":\"restart\"}' | /tmp/luci.system-hub call service_action\n</code></pre>"},{"location":"luci-development-reference/#deployment-script","title":"Deployment Script","text":"<p>Use a deployment script for fast iteration:</p> <pre><code>#!/bin/bash\n# deploy-system-hub.sh\n\nROUTER=\"root@192.168.8.191\"\n\necho \"\ud83d\ude80 Deploying system-hub to $ROUTER\"\n\n# Deploy API module\nscp luci-app-system-hub/htdocs/luci-static/resources/system-hub/api.js \\\n \"$ROUTER:/www/luci-static/resources/system-hub/\"\n\n# Deploy views\nscp luci-app-system-hub/htdocs/luci-static/resources/view/system-hub/*.js \\\n \"$ROUTER:/www/luci-static/resources/view/system-hub/\"\n\n# Deploy RPCD backend\nscp luci-app-system-hub/root/usr/libexec/rpcd/luci.system-hub \\\n \"$ROUTER:/usr/libexec/rpcd/\"\n\n# Deploy ACL\nscp luci-app-system-hub/root/usr/share/rpcd/acl.d/luci-app-system-hub.json \\\n \"$ROUTER:/usr/share/rpcd/acl.d/\"\n\n# Set permissions and restart\nssh \"$ROUTER\" \"chmod +x /usr/libexec/rpcd/luci.system-hub && /etc/init.d/rpcd restart\"\n\necho \"\u2705 Deployment complete! Clear browser cache (Ctrl+Shift+R)\"\n</code></pre>"},{"location":"luci-development-reference/#browser-testing","title":"Browser Testing","text":"<ol> <li>Open browser console (F12)</li> <li>Navigate to module page</li> <li>Check for errors:</li> <li>RPC errors (object not found, method not found, access denied)</li> <li>JavaScript errors (api.method is not a function)</li> <li>404 errors (view files not found)</li> <li>Test functionality:</li> <li>Load data displays correctly</li> <li>Actions work (start/stop services, save settings)</li> <li>No \"NaN\", \"undefined\", or empty values</li> </ol>"},{"location":"luci-development-reference/#remote-ubus-testing","title":"Remote ubus Testing","text":"<p>Test RPCD methods on router:</p> <pre><code># List all methods\nssh router \"ubus list luci.system-hub\"\n\n# Call method without parameters\nssh router \"ubus call luci.system-hub status\"\n\n# Call method with parameters\nssh router \"ubus call luci.system-hub service_action '{\\\"service\\\":\\\"network\\\",\\\"action\\\":\\\"restart\\\"}'\"\n\n# Pretty-print JSON output\nssh router \"ubus call luci.system-hub get_health | jsonlint\"\n</code></pre>"},{"location":"luci-development-reference/#debugging-tips","title":"Debugging Tips","text":"<p>Enable RPCD debug logging: <pre><code># Edit /etc/init.d/rpcd\n# Add -v flag to procd_set_param command\nprocd_set_param command \"$PROG\" -v\n\n# Restart RPCD\n/etc/init.d/rpcd restart\n\n# Watch logs\nlogread -f | grep rpcd\n</code></pre></p> <p>Enable JavaScript console logging: <pre><code>// Add to api.js\nconsole.log('\ud83d\udd27 API v0.1.0 loaded at', new Date().toISOString());\n\n// Add to views\nconsole.log('Loading health data...');\nAPI.getHealth().then(function(data) {\n console.log('Health data:', data);\n});\n</code></pre></p> <p>Test JSON output: <pre><code># On router\n/usr/libexec/rpcd/luci.system-hub call get_health | jsonlint\n\n# Check for common errors\n# - Missing commas\n# - Trailing commas\n# - Unquoted keys\n# - Invalid escape sequences\n</code></pre></p>"},{"location":"luci-development-reference/#best-practices-summary","title":"Best Practices Summary","text":""},{"location":"luci-development-reference/#do","title":"DO:","text":"<p>\u2705 Use <code>luci.</code> prefix for all ubus objects \u2705 Name RPCD scripts to match ubus object exactly \u2705 Use <code>baseclass.extend()</code> for API modules \u2705 Import APIs with <code>'require module/api as API'</code> pattern \u2705 Add null/undefined checks in frontend: <code>health.cpu?.usage || 0</code> \u2705 Validate JSON with <code>jsonlint</code> before deploying \u2705 Test with <code>ubus call</code> before browser testing \u2705 Restart RPCD after backend changes \u2705 Clear browser cache after frontend changes \u2705 Run <code>./secubox-tools/validate-modules.sh</code> before committing</p>"},{"location":"luci-development-reference/#dont","title":"DON'T:","text":"<p>\u274c Use ubus object names without <code>luci.</code> prefix \u274c Use <code>baseclass.singleton()</code> or plain objects for API modules \u274c Import APIs with <code>L.require('module.path')</code> (returns class, not instance) \u274c Forget to add methods to ACL file \u274c Mix up read/write methods in ACL sections \u274c Output non-JSON from RPCD scripts \u274c Use inconsistent data structures between backend and frontend \u274c Deploy without testing locally first \u274c Assume data exists - always check for null/undefined \u274c Forget to make RPCD scripts executable (<code>chmod +x</code>)</p>"},{"location":"luci-development-reference/#version-history","title":"Version History","text":"<p>v1.0 (2025-12-26) - Initial reference guide - Based on luci-app-secubox v1.0.0 and luci-app-system-hub v0.1.0 - Documented all critical patterns and common errors - Validated against real-world implementation challenges</p>"},{"location":"luci-development-reference/#references","title":"References","text":"<ul> <li>OpenWrt Documentation: https://openwrt.org/docs/guide-developer/start</li> <li>LuCI Documentation: https://github.com/openwrt/luci/wiki</li> <li>ubus Documentation: https://openwrt.org/docs/techref/ubus</li> <li>UCI Documentation: https://openwrt.org/docs/guide-user/base-system/uci</li> <li>jshn.sh Library: <code>/usr/share/libubox/jshn.sh</code> on OpenWrt</li> </ul>"},{"location":"luci-development-reference/#contact","title":"Contact","text":"<p>For questions or contributions to this reference guide: - Author: CyberMind contact@cybermind.fr - Project: SecuBox OpenWrt - Repository: https://github.com/cybermind-fr/secubox-openwrt</p> <p>END OF REFERENCE GUIDE</p>"},{"location":"module-implementation-guide/","title":"SecuBox Module Implementation Guide","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active Purpose: Complete guide for regenerating SecuBox modules matching the live demo</p>"},{"location":"module-implementation-guide/#see-also","title":"See Also","text":"<ul> <li>Automation Briefing: CODEX.md</li> <li>Module Prompts: FEATURE-REGENERATION-PROMPTS.md</li> <li>Code Templates: CODE-TEMPLATES.md</li> <li>Quick Commands: QUICK-START.md</li> </ul>"},{"location":"module-implementation-guide/#quick-navigation","title":"Quick Navigation","text":"<p>\ud83d\udccb FEATURE-REGENERATION-PROMPTS.md - Complete feature specifications for all 15 modules \ud83d\udcbb CODE-TEMPLATES.md - Ready-to-use code templates and implementation examples \ud83c\udfd7\ufe0f DEVELOPMENT-GUIDELINES.md - Complete development guidelines and design system \u26a1 QUICK-START.md - Quick reference for common tasks \ud83d\udd27 CLAUDE.md - Build system and architecture reference</p>"},{"location":"module-implementation-guide/#document-overview","title":"Document Overview","text":"<p>This guide shows you how to use the comprehensive documentation to regenerate or create SecuBox modules that match the live demo at secubox.cybermood.eu.</p>"},{"location":"module-implementation-guide/#whats-included","title":"What's Included","text":"<ol> <li>Feature Specifications - Detailed requirements for all 15 modules</li> <li>Code Templates - Working implementation examples</li> <li>Design System - CSS variables, typography, components</li> <li>Validation Tools - Automated testing and fixing</li> <li>Deployment Scripts - Local build and remote deployment</li> </ol>"},{"location":"module-implementation-guide/#implementation-workflow","title":"Implementation Workflow","text":""},{"location":"module-implementation-guide/#step-1-choose-your-approach","title":"Step 1: Choose Your Approach","text":"<p>Option A: Use Claude.ai for Code Generation 1. Open claude.ai 2. Copy the relevant module prompt from FEATURE-REGENERATION-PROMPTS.md 3. Paste the prompt and request implementation 4. Claude will generate all required files based on the templates 5. Review and integrate the generated code</p> <p>Option B: Manual Implementation Using Templates 1. Copy templates from CODE-TEMPLATES.md 2. Replace placeholders with module-specific values 3. Implement module-specific logic 4. Validate and test</p> <p>Option C: Hybrid Approach (Recommended) 1. Use Claude.ai for initial code generation 2. Refine using templates and guidelines 3. Validate with automated tools 4. Deploy and test on target device</p>"},{"location":"module-implementation-guide/#step-by-step-regenerate-a-module-with-claudeai","title":"Step-by-Step: Regenerate a Module with Claude.ai","text":""},{"location":"module-implementation-guide/#example-regenerating-system-hub-module","title":"Example: Regenerating System Hub Module","text":""},{"location":"module-implementation-guide/#1-gather-context","title":"1. Gather Context","text":"<p>Before prompting Claude, gather these resources:</p> <pre><code># Read the module specification\ncat FEATURE-REGENERATION-PROMPTS.md | grep -A 200 \"System Hub\"\n\n# Review the design system\ncat DEVELOPMENT-GUIDELINES.md | grep -A 100 \"Design System\"\n\n# Check existing implementation (if available)\nls -la luci-app-system-hub/\n</code></pre>"},{"location":"module-implementation-guide/#2-prepare-the-prompt","title":"2. Prepare the Prompt","text":"<p>Create a comprehensive prompt for Claude.ai:</p> <pre><code>I need you to implement the System Hub module for OpenWrt LuCI framework.\n\nIMPORTANT CONSTRAINTS:\n- OpenWrt uses LuCI framework (not React/Vue)\n- JavaScript uses L.view.extend() pattern (not ES6 modules)\n- Backend is RPCD (shell scripts) communicating via ubus\n- CSS must use variables from system-hub/common.css\n- All code must be production-ready and match live demo\n- Follow the design system exactly\n\nTECHNICAL REQUIREMENTS:\n- RPCD script MUST be named: luci.system-hub\n- Menu paths MUST match view file locations\n- Use CSS variables (--sh-*) for all colors\n- Support dark mode with [data-theme=\"dark\"]\n- Implement proper error handling\n- Add loading states for async operations\n\nREFERENCE DOCUMENTS:\n1. Live Demo: https://secubox.cybermood.eu/system-hub\n2. Feature Specification: [paste from FEATURE-REGENERATION-PROMPTS.md]\n3. Code Templates: [paste relevant templates from CODE-TEMPLATES.md]\n\nPlease provide:\n1. Complete JavaScript view files (overview.js, services.js, etc.)\n2. RPCD backend script (luci.system-hub)\n3. API module (system-hub/api.js)\n4. CSS styles (system-hub/dashboard.css)\n5. Menu configuration JSON\n6. ACL configuration JSON\n\nMake sure all code matches the live demo visual design and functionality.\n</code></pre>"},{"location":"module-implementation-guide/#3-generate-code","title":"3. Generate Code","text":"<p>Paste your prompt into Claude.ai and let it generate the implementation.</p>"},{"location":"module-implementation-guide/#4-review-generated-code","title":"4. Review Generated Code","text":"<p>Check the generated code against these requirements:</p> <p>API Module Checklist: - [ ] Uses <code>'use strict';</code> - [ ] Requires <code>baseclass</code> and <code>rpc</code> - [ ] All RPC methods use <code>rpc.declare()</code> - [ ] Object names match RPCD script name (<code>luci.system-hub</code>) - [ ] Helper functions included if needed - [ ] Exports from <code>baseclass.extend()</code></p> <p>View Module Checklist: - [ ] Extends <code>view.extend()</code> - [ ] Implements <code>load()</code> method returning Promise - [ ] Implements <code>render(data)</code> method - [ ] Uses <code>E()</code> helper for DOM building - [ ] Implements <code>poll.add()</code> for auto-refresh - [ ] Proper error handling with try/catch - [ ] Uses <code>ui.showModal()</code> for loading states - [ ] Uses <code>ui.addNotification()</code> for user feedback</p> <p>RPCD Backend Checklist: - [ ] Starts with <code>#!/bin/sh</code> - [ ] Sources <code>/lib/functions.sh</code> and <code>/usr/share/libubox/jshn.sh</code> - [ ] Implements <code>list</code> case with method declarations - [ ] Implements <code>call</code> case with method routing - [ ] All methods output valid JSON using <code>json_*</code> functions - [ ] Proper parameter validation - [ ] Error handling with appropriate messages</p> <p>Menu JSON Checklist: - [ ] Paths follow <code>admin/secubox/<category>/<module></code> - [ ] First entry uses <code>\"type\": \"firstchild\"</code> - [ ] View entries use <code>\"type\": \"view\"</code> with correct <code>\"path\"</code> - [ ] Paths match view file locations - [ ] Proper <code>\"order\"</code> values for menu positioning - [ ] Depends on correct ACL entry</p> <p>ACL JSON Checklist: - [ ] Entry name matches package name - [ ] All read methods listed under <code>\"read\".\"ubus\"</code> - [ ] All write methods listed under <code>\"write\".\"ubus\"</code> - [ ] ubus object names match RPCD script name - [ ] UCI config access granted if needed</p> <p>CSS Checklist: - [ ] Imports <code>system-hub/common.css</code> - [ ] Uses CSS variables (<code>var(--sh-*)</code>) - [ ] Supports dark mode with <code>[data-theme=\"dark\"]</code> - [ ] Responsive grid layouts - [ ] Smooth transitions and animations - [ ] JetBrains Mono for numeric values</p>"},{"location":"module-implementation-guide/#5-integrate-into-codebase","title":"5. Integrate into Codebase","text":"<pre><code># Create module directory structure\nmkdir -p luci-app-system-hub/htdocs/luci-static/resources/system-hub\nmkdir -p luci-app-system-hub/htdocs/luci-static/resources/view/system-hub\nmkdir -p luci-app-system-hub/root/usr/libexec/rpcd\nmkdir -p luci-app-system-hub/root/usr/share/luci/menu.d\nmkdir -p luci-app-system-hub/root/usr/share/rpcd/acl.d\n\n# Copy generated files to appropriate locations\n# (Copy from Claude's output to respective files)\n\n# Set RPCD script as executable\nchmod +x luci-app-system-hub/root/usr/libexec/rpcd/luci.system-hub\n</code></pre>"},{"location":"module-implementation-guide/#6-validate-implementation","title":"6. Validate Implementation","text":"<pre><code># Fix permissions first (CRITICAL)\n./secubox-tools/fix-permissions.sh --local\n\n# Run comprehensive validation (7 checks)\n./secubox-tools/validate-modules.sh\n\n# Expected output:\n# \u2705 All checks passed\n# OR\n# \u274c Errors found with specific fix instructions\n</code></pre>"},{"location":"module-implementation-guide/#7-build-locally","title":"7. Build Locally","text":"<pre><code># Build single module\n./secubox-tools/local-build.sh build luci-app-system-hub\n\n# Or build all modules\n./secubox-tools/local-build.sh build\n\n# Or full validation + build\n./secubox-tools/local-build.sh full\n</code></pre>"},{"location":"module-implementation-guide/#8-deploy-to-test-router","title":"8. Deploy to Test Router","text":"<pre><code># Transfer package\nscp build/x86-64/luci-app-system-hub*.ipk root@192.168.1.1:/tmp/\n\n# Install on router\nssh root@192.168.1.1 << 'EOF'\nopkg install /tmp/luci-app-system-hub*.ipk\n/etc/init.d/rpcd restart\n/etc/init.d/uhttpd restart\nEOF\n\n# Fix permissions on deployed router (if needed)\n./secubox-tools/fix-permissions.sh --remote\n</code></pre>"},{"location":"module-implementation-guide/#9-test-in-browser","title":"9. Test in Browser","text":"<ol> <li>Navigate to <code>http://192.168.1.1/cgi-bin/luci</code></li> <li>Go to SecuBox \u2192 System \u2192 System Hub</li> <li>Verify:</li> <li>Page loads without errors</li> <li>Data displays correctly</li> <li>Actions work (buttons, forms)</li> <li>Auto-refresh updates data</li> <li>Styling matches demo</li> <li>Dark mode works</li> <li>Responsive design works on mobile</li> </ol>"},{"location":"module-implementation-guide/#10-iterate-and-refine","title":"10. Iterate and Refine","text":"<p>If issues found: 1. Check browser console for JavaScript errors 2. Check router logs: <code>ssh root@192.168.1.1 \"logread | tail -50\"</code> 3. Verify RPCD methods work: <code>ubus call luci.system-hub status</code> 4. Fix issues in local files 5. Rebuild and redeploy 6. Test again</p>"},{"location":"module-implementation-guide/#common-implementation-patterns","title":"Common Implementation Patterns","text":""},{"location":"module-implementation-guide/#pattern-1-multi-tab-dashboard","title":"Pattern 1: Multi-Tab Dashboard","text":"<p>Example: System Hub with 9 tabs</p> <pre><code>// In render()\nvar tabs = [\n { id: 'overview', title: 'Overview', icon: '\ud83c\udfe0' },\n { id: 'services', title: 'Services', icon: '\u2699\ufe0f' },\n { id: 'logs', title: 'Logs', icon: '\ud83d\udccb' }\n];\n\nvar activeTab = 'overview';\n\n// Render tab navigation\nvar tabNav = E('div', { 'class': 'sh-nav-tabs' },\n tabs.map(function(tab) {\n return E('div', {\n 'class': 'sh-nav-tab' + (activeTab === tab.id ? ' active' : ''),\n 'click': function() {\n // Switch tab logic\n document.querySelectorAll('.sh-nav-tab').forEach(function(t) {\n t.classList.remove('active');\n });\n this.classList.add('active');\n // Show/hide tab content\n }\n }, [\n E('span', {}, tab.icon),\n E('span', {}, tab.title)\n ]);\n })\n);\n\n// Render tab content\nvar tabContent = E('div', { 'class': 'tab-content' }, [\n // Overview tab\n E('div', { 'class': 'tab-pane' + (activeTab === 'overview' ? ' active' : ''), 'data-tab': 'overview' }, [\n this.renderOverviewContent()\n ]),\n // Services tab\n E('div', { 'class': 'tab-pane' + (activeTab === 'services' ? ' active' : ''), 'data-tab': 'services' }, [\n this.renderServicesContent()\n ])\n]);\n</code></pre>"},{"location":"module-implementation-guide/#pattern-2-filter-tabs-with-data-filtering","title":"Pattern 2: Filter Tabs with Data Filtering","text":"<p>Example: SecuBox module grid with category filtering</p> <pre><code>// Filter tabs\nvar filterTabs = E('div', { 'class': 'sh-filter-tabs' }, [\n E('div', {\n 'class': 'sh-filter-tab active',\n 'data-filter': 'all',\n 'click': function(ev) {\n document.querySelectorAll('.sh-filter-tab').forEach(function(t) {\n t.classList.remove('active');\n });\n this.classList.add('active');\n self.filterModules('all');\n }\n }, [\n E('span', { 'class': 'sh-tab-icon' }, '\ud83d\udce6'),\n E('span', { 'class': 'sh-tab-label' }, 'All')\n ]),\n E('div', {\n 'class': 'sh-filter-tab',\n 'data-filter': 'security',\n 'click': function(ev) {\n document.querySelectorAll('.sh-filter-tab').forEach(function(t) {\n t.classList.remove('active');\n });\n this.classList.add('active');\n self.filterModules('security');\n }\n }, [\n E('span', { 'class': 'sh-tab-icon' }, '\ud83d\udee1\ufe0f'),\n E('span', { 'class': 'sh-tab-label' }, 'Security')\n ])\n]);\n\n// Filter function\nfilterModules: function(category) {\n var modules = document.querySelectorAll('.module-card');\n modules.forEach(function(module) {\n if (category === 'all' || module.dataset.category === category) {\n module.style.display = 'block';\n } else {\n module.style.display = 'none';\n }\n });\n}\n</code></pre>"},{"location":"module-implementation-guide/#pattern-3-real-time-log-viewer","title":"Pattern 3: Real-Time Log Viewer","text":"<p>Example: System Hub logs tab</p> <pre><code>// Logs view with auto-scroll and auto-refresh\nrenderLogsTab: function() {\n var self = this;\n var autoScroll = true;\n var autoRefresh = true;\n var refreshInterval = 5; // seconds\n\n var logsContainer = E('div', { 'class': 'logs-container' });\n\n // Load logs\n var loadLogs = function() {\n API.getLogs(100, '').then(function(result) {\n var logs = result.logs || [];\n\n dom.content(logsContainer,\n logs.map(function(log) {\n return E('div', { 'class': 'log-line' }, log);\n })\n );\n\n // Auto-scroll to bottom\n if (autoScroll) {\n logsContainer.scrollTop = logsContainer.scrollHeight;\n }\n });\n };\n\n // Initial load\n loadLogs();\n\n // Auto-refresh\n if (autoRefresh) {\n setInterval(loadLogs, refreshInterval * 1000);\n }\n\n return E('div', {}, [\n // Controls\n E('div', { 'class': 'logs-controls' }, [\n E('label', {}, [\n E('input', {\n 'type': 'checkbox',\n 'checked': autoScroll,\n 'change': function() { autoScroll = this.checked; }\n }),\n ' Auto-scroll'\n ]),\n E('label', {}, [\n E('input', {\n 'type': 'checkbox',\n 'checked': autoRefresh,\n 'change': function() { autoRefresh = this.checked; }\n }),\n ' Auto-refresh'\n ]),\n E('button', {\n 'class': 'sh-btn sh-btn-primary',\n 'click': loadLogs\n }, '\ud83d\udd04 Refresh Now')\n ]),\n // Logs display\n logsContainer\n ]);\n}\n</code></pre>"},{"location":"module-implementation-guide/#pattern-4-action-buttons-with-confirmation","title":"Pattern 4: Action Buttons with Confirmation","text":"<p>Example: Service management buttons</p> <pre><code>// Render action button with confirmation\nrenderActionButton: function(service, action, label, btnClass) {\n var self = this;\n\n return E('button', {\n 'class': 'sh-btn ' + btnClass,\n 'click': function(ev) {\n // Show confirmation modal\n ui.showModal(_('Confirm Action'), [\n E('p', {}, _('Are you sure you want to %s service %s?').format(action, service)),\n E('div', { 'class': 'right' }, [\n E('button', {\n 'class': 'sh-btn sh-btn-secondary',\n 'click': ui.hideModal\n }, _('Cancel')),\n E('button', {\n 'class': 'sh-btn sh-btn-primary',\n 'click': function() {\n ui.hideModal();\n self.performServiceAction(service, action);\n }\n }, _('Confirm'))\n ])\n ]);\n }\n }, label);\n},\n\n// Perform service action\nperformServiceAction: function(service, action) {\n var self = this;\n\n ui.showModal(_('Performing Action'), [\n E('p', {}, E('em', { 'class': 'spinning' }, _('Please wait...')))\n ]);\n\n API.serviceAction(service, action).then(function(result) {\n ui.hideModal();\n\n if (result.success) {\n ui.addNotification(null, E('p', _('Action completed successfully')), 'success');\n self.handleRefresh();\n } else {\n ui.addNotification(null, E('p', _('Action failed: %s').format(result.message)), 'error');\n }\n }).catch(function(error) {\n ui.hideModal();\n ui.addNotification(null, E('p', _('Error: %s').format(error.message)), 'error');\n });\n}\n</code></pre>"},{"location":"module-implementation-guide/#pattern-5-form-with-validation","title":"Pattern 5: Form with Validation","text":"<p>Example: Settings page</p> <pre><code>renderSettingsForm: function() {\n var self = this;\n var settings = this.settingsData || {};\n\n return E('form', { 'class': 'settings-form' }, [\n // Text input\n E('div', { 'class': 'form-group' }, [\n E('label', {}, 'Hostname'),\n E('input', {\n 'type': 'text',\n 'class': 'form-control',\n 'value': settings.hostname || '',\n 'id': 'input-hostname'\n })\n ]),\n\n // Number input with validation\n E('div', { 'class': 'form-group' }, [\n E('label', {}, 'Refresh Interval (seconds)'),\n E('input', {\n 'type': 'number',\n 'class': 'form-control',\n 'value': settings.refresh_interval || 30,\n 'min': 10,\n 'max': 300,\n 'id': 'input-refresh'\n })\n ]),\n\n // Checkbox\n E('div', { 'class': 'form-group' }, [\n E('label', {}, [\n E('input', {\n 'type': 'checkbox',\n 'checked': settings.auto_refresh || false,\n 'id': 'input-auto-refresh'\n }),\n ' Enable auto-refresh'\n ])\n ]),\n\n // Submit button\n E('div', { 'class': 'form-actions' }, [\n E('button', {\n 'class': 'sh-btn sh-btn-primary',\n 'type': 'submit',\n 'click': function(ev) {\n ev.preventDefault();\n self.handleSaveSettings();\n }\n }, 'Save Settings')\n ])\n ]);\n},\n\nhandleSaveSettings: function() {\n var hostname = document.getElementById('input-hostname').value;\n var refreshInterval = parseInt(document.getElementById('input-refresh').value);\n var autoRefresh = document.getElementById('input-auto-refresh').checked;\n\n // Validate\n if (!hostname) {\n ui.addNotification(null, E('p', _('Hostname is required')), 'error');\n return;\n }\n\n if (refreshInterval < 10 || refreshInterval > 300) {\n ui.addNotification(null, E('p', _('Refresh interval must be between 10 and 300 seconds')), 'error');\n return;\n }\n\n // Save via API\n API.saveSettings(hostname, refreshInterval, autoRefresh).then(function(result) {\n if (result.success) {\n ui.addNotification(null, E('p', _('Settings saved successfully')), 'success');\n } else {\n ui.addNotification(null, E('p', _('Failed to save settings: %s').format(result.message)), 'error');\n }\n });\n}\n</code></pre>"},{"location":"module-implementation-guide/#module-specific-notes","title":"Module-Specific Notes","text":""},{"location":"module-implementation-guide/#system-hub-luci-app-system-hub","title":"System Hub (luci-app-system-hub)","text":"<ul> <li>Complexity: High - 9 tabs, many features</li> <li>Key Features: Health monitoring, service management, system logs, backup/restore</li> <li>Special Requirements: Integration with SecuBox for components list</li> <li>Dependencies: Calls <code>luci.secubox</code> for module enumeration</li> </ul>"},{"location":"module-implementation-guide/#wireguard-dashboard-luci-app-wireguard-dashboard","title":"WireGuard Dashboard (luci-app-wireguard-dashboard)","text":"<ul> <li>Complexity: Medium</li> <li>Key Features: Peer management, QR code generation, traffic stats</li> <li>Special Requirements: QR code generation (use qrencode or JavaScript library)</li> <li>Dependencies: WireGuard tools (<code>wg</code> command)</li> </ul>"},{"location":"module-implementation-guide/#crowdsec-dashboard-luci-app-crowdsec-dashboard","title":"CrowdSec Dashboard (luci-app-crowdsec-dashboard)","text":"<ul> <li>Complexity: Medium</li> <li>Key Features: Threat intelligence, decisions management, bouncers</li> <li>Special Requirements: Parse CrowdSec CLI output</li> <li>Dependencies: CrowdSec (<code>cscli</code> command)</li> </ul>"},{"location":"module-implementation-guide/#netdata-dashboard-luci-app-netdata-dashboard","title":"Netdata Dashboard (luci-app-netdata-dashboard)","text":"<ul> <li>Complexity: Low - mostly embedding iframe</li> <li>Key Features: Embedded Netdata UI, quick metrics overview</li> <li>Special Requirements: Netdata API integration</li> <li>Dependencies: Netdata service</li> </ul>"},{"location":"module-implementation-guide/#network-modes-luci-app-network-modes","title":"Network Modes (luci-app-network-modes)","text":"<ul> <li>Complexity: High - UCI manipulation</li> <li>Key Features: Network topology wizard, configuration preview</li> <li>Special Requirements: UCI config validation, rollback mechanism</li> <li>Dependencies: Network, firewall, DHCP configs</li> </ul>"},{"location":"module-implementation-guide/#available-modes-v036","title":"Available Modes (v0.3.6)","text":"<p>The production build now includes nine fully supported profiles. Each profile exposes its own RPC (<code>*_config</code>), view, and default values under <code>network-modes.<mode></code>:</p> Mode ID Description Notable Features <code>router</code> Standard router NAT + firewall, DHCP, proxy/HTTPS front-end helpers <code>doublenat</code> Behind ISP CPE WAN DHCP client, isolated LAN/guest bridge, UPnP/DMZ controls <code>multiwan</code> Dual uplink Health checks, failover hold timers, load-balance/mwan3 <code>vpnrelay</code> VPN gateway WireGuard/OpenVPN, kill switch, DNS override, split tunnel <code>bridge</code> Layer-2 pass-through No NAT, all ports bridged, DHCP client <code>accesspoint</code> WiFi AP Bridge upstream, disable routing/DHCP, 802.11r/k/v toggles <code>relay</code> WiFi repeater STA+AP, relayd/WDS, WireGuard assist, MTU/MSS tuning <code>travel</code> Portable router Client WiFi scan, MAC clone, WPA3 hotspot, sandbox LAN <code>sniffer</code> TAP/sniffer Promiscuous bridge, Netifyd integration, pcap support <p>When adding another mode, update: UCI defaults (<code>root/etc/config/network-modes</code>), the RPC script (<code>get_<mode>_config</code>, <code>update_settings</code>, <code>generate_config</code>, <code>set_mode</code> allow-list), the JS API/view/menu, and the docs.</p>"},{"location":"module-implementation-guide/#troubleshooting-guide","title":"Troubleshooting Guide","text":""},{"location":"module-implementation-guide/#issue-object-not-found-error","title":"Issue: \"Object not found\" Error","text":"<p>Symptoms: <pre><code>RPC call to luci.module-name/method failed with error -32000: Object not found\n</code></pre></p> <p>Diagnosis: <pre><code># 1. Check RPCD script exists and is executable\nls -la luci-app-module-name/root/usr/libexec/rpcd/\n\n# 2. Check RPCD script name matches ubus object\ngrep \"object:\" luci-app-module-name/htdocs/luci-static/resources/module-name/api.js\n\n# 3. Test RPCD script manually\nssh root@router \"/usr/libexec/rpcd/luci.module-name list\"\n\n# 4. Check RPCD logs\nssh root@router \"logread | grep rpcd | tail -20\"\n</code></pre></p> <p>Solutions: 1. Rename RPCD script to match ubus object name (must include <code>luci.</code> prefix) 2. Make script executable: <code>chmod +x luci.module-name</code> 3. Restart RPCD: <code>/etc/init.d/rpcd restart</code> 4. Reinstall package if deployed</p>"},{"location":"module-implementation-guide/#issue-view-not-loading-404","title":"Issue: View Not Loading (404)","text":"<p>Symptoms: <pre><code>HTTP error 404 while loading class file '/luci-static/resources/view/module-name/overview.js'\n</code></pre></p> <p>Diagnosis: <pre><code># 1. Check menu path\ncat luci-app-module-name/root/usr/share/luci/menu.d/*.json | grep \"path\"\n\n# 2. Check view file exists\nls -la luci-app-module-name/htdocs/luci-static/resources/view/\n\n# 3. Verify paths match\n# Menu: \"path\": \"module-name/overview\"\n# File: view/module-name/overview.js\n</code></pre></p> <p>Solutions: 1. Update menu path to match view file location 2. OR move view files to match menu path 3. Rebuild and redeploy package</p>"},{"location":"module-implementation-guide/#issue-css-not-applied","title":"Issue: CSS Not Applied","text":"<p>Symptoms: - Unstyled page - Missing colors, fonts, or layout</p> <p>Diagnosis: <pre><code># 1. Check browser console for CSS 404 errors\n# (Open browser developer tools)\n\n# 2. Verify CSS import in view file\ngrep \"stylesheet\" luci-app-module-name/htdocs/luci-static/resources/view/*/overview.js\n\n# 3. Check CSS file exists\nls -la luci-app-module-name/htdocs/luci-static/resources/module-name/dashboard.css\n</code></pre></p> <p>Solutions: 1. Verify CSS import path: <code>L.resource('module-name/dashboard.css')</code> 2. Import common.css: <code>@import url('../system-hub/common.css');</code> 3. Check file permissions: <code>644</code> for CSS files 4. Clear browser cache (Ctrl+Shift+R)</p>"},{"location":"module-implementation-guide/#issue-data-not-updating","title":"Issue: Data Not Updating","text":"<p>Symptoms: - Dashboard shows stale data - Auto-refresh not working</p> <p>Diagnosis: <pre><code># 1. Check poll is registered\n# (Look for poll.add() in render() method)\n\n# 2. Check API calls return Promises\n# (Verify methods return results from rpc.declare())\n\n# 3. Test API methods directly\nssh root@router \"ubus call luci.module-name status\"\n</code></pre></p> <p>Solutions: 1. Add poll.add() to render() method 2. Verify API calls in poll callback return Promises 3. Ensure updateDashboard() updates correct DOM elements 4. Check browser console for JavaScript errors</p>"},{"location":"module-implementation-guide/#best-practices","title":"Best Practices","text":""},{"location":"module-implementation-guide/#1-code-organization","title":"1. Code Organization","text":"<p>DO: - Keep related code together (API methods, helpers) - Use descriptive variable and function names - Add comments for complex logic - Break large functions into smaller helpers</p> <p>DON'T: - Put all code in one massive function - Use single-letter variable names (except in loops) - Duplicate code - create helper functions instead - Leave commented-out code in production</p>"},{"location":"module-implementation-guide/#2-error-handling","title":"2. Error Handling","text":"<p>DO: <pre><code>API.getData().then(function(result) {\n if (result && result.data) {\n // Process data\n } else {\n console.warn('No data returned');\n // Show empty state\n }\n}).catch(function(error) {\n console.error('API error:', error);\n ui.addNotification(null, E('p', 'Failed to load data'), 'error');\n});\n</code></pre></p> <p>DON'T: <pre><code>API.getData().then(function(result) {\n // Process data without checking\n result.data.forEach(function(item) { ... }); // Will crash if data is null\n});\n</code></pre></p>"},{"location":"module-implementation-guide/#3-performance","title":"3. Performance","text":"<p>DO: - Use poll.add() instead of setInterval for auto-refresh - Update specific DOM elements instead of full re-render - Debounce search inputs - Lazy load data only when needed</p> <p>DON'T: - Re-render entire view on every update - Poll too frequently (<10 seconds) - Load all data upfront - Perform expensive operations in render()</p>"},{"location":"module-implementation-guide/#4-user-experience","title":"4. User Experience","text":"<p>DO: - Show loading states (spinners, skeleton screens) - Provide feedback for actions (success/error notifications) - Confirm destructive actions (delete, restart) - Use descriptive error messages</p> <p>DON'T: - Leave users waiting without feedback - Silent failures - Generic error messages (\"Error occurred\") - Allow destructive actions without confirmation</p>"},{"location":"module-implementation-guide/#deployment-checklist","title":"Deployment Checklist","text":"<p>Before deploying to production:</p> <ul> <li> Code Quality</li> <li> All validation checks pass</li> <li> No JavaScript errors in console</li> <li> No shell script errors (shellcheck)</li> <li> <p> All JSON files valid (jsonlint)</p> </li> <li> <p> Functionality</p> </li> <li> All tabs/pages load correctly</li> <li> All actions work as expected</li> <li> Data displays correctly</li> <li> Auto-refresh updates data</li> <li> Forms validate input</li> <li> <p> Error handling works</p> </li> <li> <p> Design</p> </li> <li> Matches live demo visually</li> <li> Dark mode works</li> <li> Responsive on mobile</li> <li> Consistent with other modules</li> <li> <p> No layout issues</p> </li> <li> <p> Performance</p> </li> <li> Page loads quickly (<2s)</li> <li> Auto-refresh doesn't freeze UI</li> <li> No memory leaks</li> <li> <p> Efficient data fetching</p> </li> <li> <p> Security</p> </li> <li> ACL permissions correct</li> <li> Input validation on frontend and backend</li> <li> No hardcoded credentials</li> <li> <p> Safe command execution (no injection)</p> </li> <li> <p> Documentation</p> </li> <li> README.md updated</li> <li> Comments in complex code</li> <li> Menu entries have descriptions</li> <li> ACL entries have descriptions</li> </ul>"},{"location":"module-implementation-guide/#additional-resources","title":"Additional Resources","text":""},{"location":"module-implementation-guide/#documentation","title":"Documentation","text":"<ul> <li>LuCI API Reference</li> <li>OpenWrt Developer Guide</li> <li>UCI Configuration</li> <li>ubus Documentation</li> </ul>"},{"location":"module-implementation-guide/#live-demo","title":"Live Demo","text":"<ul> <li>Main Demo: https://secubox.cybermood.eu</li> <li>System Hub: https://secubox.cybermood.eu/system-hub</li> <li>CrowdSec: https://secubox.cybermood.eu/crowdsec</li> <li>WireGuard: https://secubox.cybermood.eu/wireguard</li> </ul>"},{"location":"module-implementation-guide/#internal-documentation","title":"Internal Documentation","text":"<ul> <li>FEATURE-REGENERATION-PROMPTS.md - All module specifications</li> <li>CODE-TEMPLATES.md - Implementation templates</li> <li>DEVELOPMENT-GUIDELINES.md - Complete dev guide</li> <li>QUICK-START.md - Quick reference</li> <li>CLAUDE.md - Build system reference</li> </ul>"},{"location":"module-implementation-guide/#tools","title":"Tools","text":"<ul> <li>SecuBox Tools - Validation, build, deployment scripts</li> <li>GitHub Actions - CI/CD workflows</li> <li>Templates - Module templates</li> </ul>"},{"location":"module-implementation-guide/#getting-help","title":"Getting Help","text":"<p>If you encounter issues not covered in this guide:</p> <ol> <li>Check Existing Modules: Look at working modules for reference implementations</li> <li>Run Validation: <code>./secubox-tools/validate-modules.sh</code> for automated checks</li> <li>Check Logs: <code>logread | grep -i error</code> on the router</li> <li>Review Documentation: Read DEVELOPMENT-GUIDELINES.md for detailed explanations</li> <li>Contact Support: support@cybermind.fr</li> </ol> <p>Document Version: 1.0.0 Last Updated: 2025-12-27 Maintainer: CyberMind.fr Live Demo: https://secubox.cybermood.eu</p>"},{"location":"module-status/","title":"SecuBox Modules - Implementation Status","text":"<p>Version: 2.0.1 Last Updated: 2025-12-30 Status: In Heavily Development Stage Total Modules: 16 Completion: 100%</p>"},{"location":"module-status/#quick-stats","title":"Quick Stats","text":"Metric Value Total Modules 16 Total Views 112 JavaScript Lines 27,138 RPCD Methods 288 Latest Release v2.0.1 Completion Rate 100%"},{"location":"module-status/#see-also","title":"See Also","text":"<ul> <li>Feature Regeneration Prompts: FEATURE-REGENERATION-PROMPTS.md</li> <li>Implementation Workflow: MODULE-IMPLEMENTATION-GUIDE.md</li> <li>Build System: CLAUDE.md</li> </ul>"},{"location":"module-status/#module-categories","title":"Module Categories","text":""},{"location":"module-status/#1-core-control-2-modules","title":"1. Core Control (2 modules)","text":""},{"location":"module-status/#luci-app-secubox","title":"luci-app-secubox","text":"<ul> <li>Version: 0.6.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: SecuBox master control dashboard</li> <li>Views: 11 (dashboard, modules, modules-minimal, modules-debug, monitoring, alerts, settings, dev-status, wizard, appstore, help)</li> <li>JavaScript Lines: 2,906</li> <li>RPCD Methods: 33 (second-largest backend)</li> <li>Key Features:</li> <li>Module auto-discovery and management</li> <li>Unified system dashboard</li> <li>Module enable/disable functionality</li> <li>Service health monitoring</li> <li>Package manager integration (opkg & apk)</li> <li>Unified alert aggregation</li> <li>Settings synchronization</li> <li>Development status reporting</li> <li>Setup wizard for first-run experience</li> <li>App store integration for manifest-driven apps</li> <li>Integration: Manages all 15 other modules, opkg/apk package detection</li> <li>Recent Updates:</li> <li>v0.6.0: Complete theme integration with secubox-theme</li> <li>Migrated all views to use CSS variables (--sh-* prefix)</li> <li>Added cyberpunk theme support across all CSS files</li> <li>Implemented Theme.init() pattern in all views</li> <li>Unified theme system with dark/light/cyberpunk variants</li> <li>v0.3.1: Enhanced permission management system</li> <li>Added .apk package format support (OpenWrt 25.12+)</li> <li>Improved module detection logic</li> </ul>"},{"location":"module-status/#luci-app-system-hub","title":"luci-app-system-hub","text":"<ul> <li>Version: 0.3.2-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Central system control and monitoring</li> <li>Views: 10 (overview, health, services, components, diagnostics, backup, remote, logs, settings, dev-status)</li> <li>JavaScript Lines: 4,454 (LARGEST implementation)</li> <li>RPCD Methods: 18</li> <li>Key Features:</li> <li>Comprehensive system information dashboard</li> <li>Real-time health monitoring (CPU, memory, disk, network)</li> <li>Service management (start/stop/restart/enable/disable)</li> <li>System diagnostics and troubleshooting</li> <li>Configuration backup/restore</li> <li>Remote management capabilities</li> <li>System logs aggregation with auto-refresh</li> <li>Component inventory tracking</li> <li>OpenWrt version detection</li> <li>Architecture detection (x86, ARM, MIPS)</li> <li>Recent Updates:</li> <li>v0.3.2: Modernized Quick Status widgets with histograms and gradients</li> <li>Added Network and Services widgets to Real-Time Metrics</li> <li>Enhanced dynamic overview stats</li> <li>Implemented working system logs viewer</li> <li>Fixed HTMLCollection display errors</li> <li>Integration: systemd/procd services, ubus, logread, opkg/apk</li> <li>Commit: fadf606 - \"feat(system-hub): enhance dynamic overview stats for v0.3.2\"</li> </ul>"},{"location":"module-status/#2-security-monitoring-2-modules","title":"2. Security & Monitoring (2 modules)","text":""},{"location":"module-status/#luci-app-crowdsec-dashboard","title":"luci-app-crowdsec-dashboard","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: CrowdSec threat intelligence and IPS dashboard</li> <li>Views: 6 (overview, alerts, decisions, bouncers, metrics, settings)</li> <li>JavaScript Lines: 2,089</li> <li>RPCD Methods: 12</li> <li>Key Features:</li> <li>Real-time threat detection and blocking</li> <li>Collaborative security intelligence sharing</li> <li>IP ban/unban management</li> <li>Multi-bouncer support (firewall, nginx, etc.)</li> <li>Threat scoring and risk analysis</li> <li>Attack metrics and trends</li> <li>Custom scenario detection</li> <li>Geographic threat analysis</li> <li>Integration: CrowdSec engine, cscli command-line, iptables/nftables</li> <li>Dependencies: crowdsec package</li> </ul>"},{"location":"module-status/#luci-app-netdata-dashboard","title":"luci-app-netdata-dashboard","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Real-time system monitoring with comprehensive metrics</li> <li>Views: 6 (dashboard, system, network, processes, realtime, settings)</li> <li>JavaScript Lines: 1,554</li> <li>RPCD Methods: 16</li> <li>Key Features:</li> <li>Real-time system metrics collection</li> <li>Per-core CPU analysis</li> <li>Memory and swap tracking</li> <li>Disk I/O monitoring</li> <li>Network interface statistics</li> <li>Process tracking and management</li> <li>System load averages</li> <li>Historical charts and trends</li> <li>Integration: /proc/stat, /proc/meminfo, /proc/net, system utilities</li> <li>Data Sources: procfs, sysfs, netlink</li> </ul>"},{"location":"module-status/#3-network-intelligence-2-modules","title":"3. Network Intelligence (2 modules)","text":""},{"location":"module-status/#luci-app-netifyd-dashboard","title":"luci-app-netifyd-dashboard","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Deep packet inspection and application classification</li> <li>Views: 7 (overview, flows, applications, devices, talkers, risks, settings)</li> <li>JavaScript Lines: 1,376</li> <li>RPCD Methods: 12</li> <li>Key Features:</li> <li>Deep packet inspection (DPI)</li> <li>Application protocol detection (HTTP, HTTPS, DNS, SSH, etc.)</li> <li>Network flow tracking and analysis</li> <li>Device fingerprinting and classification</li> <li>Risk detection and scoring</li> <li>Top talkers analysis</li> <li>Traffic pattern identification</li> <li>Port/protocol classification</li> <li>Integration: netifyd DPI engine</li> <li>Dependencies: netifyd package</li> <li>Use Cases: Traffic analysis, bandwidth optimization, security monitoring</li> </ul>"},{"location":"module-status/#luci-app-network-modes","title":"luci-app-network-modes","text":"<ul> <li>Version: 0.3.5-1</li> <li>Status: \u2705 Production Ready</li> <li>Description: Dynamic network mode switching and configuration</li> <li>Views: 7 (overview, wizard, router, relay, accesspoint, sniffer, settings)</li> <li>JavaScript Lines: 2,104</li> <li>RPCD Methods: 34 (LARGEST backend)</li> <li>Key Features:</li> <li>Five network modes:<ul> <li>Router: WAN/LAN with NAT and firewall</li> <li>Relay: IP forwarding without NAT</li> <li>Access Point: Bridge mode for wireless extension</li> <li>Sniffer: Network monitoring mode</li> <li>Custom: User-defined configuration</li> </ul> </li> <li>Automatic interface detection</li> <li>Configuration backup/restore per mode</li> <li>Live switching without reboot</li> <li>Service management per mode</li> <li>Dynamic firewall rule switching</li> <li>DHCP server/client mode switching</li> <li>Interface bridging automation</li> <li>Recent Updates:</li> <li>v0.3.5: Auto-deploy proxies (Squid/TinyProxy/Privoxy), DoH, nginx vhosts, and Let\u2019s Encrypt certificates</li> <li>Auto-apply advanced WiFi (802.11r/k/v, band steering) and tcpdump packet capture per mode</li> <li>Integration: network, firewall, DHCP, hostapd/wpa_supplicant</li> </ul>"},{"location":"module-status/#4-vpn-access-control-3-modules","title":"4. VPN & Access Control (3 modules)","text":""},{"location":"module-status/#luci-app-wireguard-dashboard","title":"luci-app-wireguard-dashboard","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: WireGuard VPN management and monitoring</li> <li>Views: 6 (overview, peers, config, qrcodes, traffic, settings)</li> <li>JavaScript Lines: 1,571</li> <li>RPCD Methods: 15</li> <li>Key Features:</li> <li>WireGuard interface management</li> <li>Peer configuration and key management</li> <li>QR code generation for mobile clients</li> <li>Real-time traffic monitoring per peer</li> <li>Configuration import/export</li> <li>Automatic key pair generation</li> <li>Server and client modes</li> <li>Configuration validation</li> <li>Peer allowed-IPs management</li> <li>Integration: wg-tools, wg command-line interface</li> <li>Dependencies: wireguard-tools, qrencode</li> <li>Supported Clients: iOS, Android, Windows, macOS, Linux</li> </ul>"},{"location":"module-status/#luci-app-client-guardian","title":"luci-app-client-guardian","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Network Access Control (NAC) and captive portal</li> <li>Views: 9 (overview, clients, zones, alerts, parental, portal, logs, captive, settings)</li> <li>JavaScript Lines: 2,293 (largest in access control category)</li> <li>RPCD Methods: 29</li> <li>Key Features:</li> <li>Network Access Control with approval workflow</li> <li>Security zones (LAN, Guest, Quarantine, DMZ)</li> <li>Client device management (approve/ban/quarantine)</li> <li>Parental controls with URL filtering</li> <li>Captive portal integration</li> <li>Real-time alerts (email/SMS notifications)</li> <li>Per-zone bandwidth limiting</li> <li>Time-based access restrictions</li> <li>Device fingerprinting and classification</li> <li>Session management</li> <li>DHCP lease tracking</li> <li>Integration: nodogsplash (captive portal), iptables/arptables, DHCP, OpenWrt firewall</li> <li>Dependencies: nodogsplash, iptables, arptables</li> </ul>"},{"location":"module-status/#luci-app-auth-guardian","title":"luci-app-auth-guardian","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Advanced authentication and voucher system</li> <li>Views: 6 (overview, sessions, vouchers, splash, oauth, bypass)</li> <li>JavaScript Lines: 312 (minimal UI, form-focused)</li> <li>RPCD Methods: 13</li> <li>Key Features:</li> <li>OAuth2 integration (Google, GitHub, Facebook, etc.)</li> <li>Voucher-based access control system</li> <li>Session management and tracking</li> <li>Captive portal splash page customization</li> <li>Multi-factor authentication support</li> <li>Access bypass rules</li> <li>Audit logging for authentication events</li> <li>Time-limited vouchers</li> <li>Guest access management</li> <li>Integration: nodogsplash, OAuth providers, UCI config</li> <li>Storage: UCI config, sessions JSON, vouchers JSON, logs JSON</li> </ul>"},{"location":"module-status/#5-bandwidth-traffic-3-modules","title":"5. Bandwidth & Traffic (3 modules)","text":""},{"location":"module-status/#luci-app-bandwidth-manager","title":"luci-app-bandwidth-manager","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Bandwidth management with QoS and quotas</li> <li>Views: 9 (overview, rules, quotas, usage, clients, media, classes, schedules, settings)</li> <li>JavaScript Lines: 936</li> <li>RPCD Methods: 14</li> <li>Key Features:</li> <li>QoS traffic shaping (HTB, CAKE, FQ_CODEL)</li> <li>Per-client data quotas and limits</li> <li>Seven-priority traffic classification:<ul> <li>Real-time (VoIP, gaming)</li> <li>High priority (video conferencing)</li> <li>Normal (web browsing)</li> <li>Low priority (downloads)</li> <li>Bulk (torrents, backups)</li> </ul> </li> <li>Real-time bandwidth usage monitoring</li> <li>Historical usage tracking</li> <li>Media streaming detection and optimization</li> <li>Bandwidth reservation per application</li> <li>Schedule-based bandwidth policies</li> <li>Quota reset automation</li> <li>Integration: tc (traffic control), iptables, conntrack</li> <li>Commit: fa9bb2a - \"feat: complete Bandwidth Manager implementation\"</li> </ul>"},{"location":"module-status/#luci-app-traffic-shaper","title":"luci-app-traffic-shaper","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Advanced traffic shaping and QoS control</li> <li>Views: 5 (overview, classes, rules, presets, stats)</li> <li>JavaScript Lines: 985</li> <li>RPCD Methods: 16</li> <li>Key Features:</li> <li>CAKE (Common Applications Kept Enhanced) qdisc support</li> <li>HTB (Hierarchical Token Bucket) support</li> <li>Traffic classes with configurable priorities</li> <li>Port and protocol-based classification rules</li> <li>Quick preset configurations:<ul> <li>Gaming: Low latency, prioritize UDP gaming ports</li> <li>Streaming: Optimize video streams, buffer management</li> <li>Work From Home: Prioritize VoIP and video conferencing</li> <li>Balanced: Default fair queueing</li> </ul> </li> <li>Real-time queue statistics</li> <li>Per-class bandwidth allocation</li> <li>Burst and ceiling rate configuration</li> <li>Latency optimization</li> <li>Integration: tc command, HTB/CAKE qdiscs, iptables marking</li> <li>Validation: \u2705 All checks passed</li> </ul>"},{"location":"module-status/#luci-app-media-flow","title":"luci-app-media-flow","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Media traffic detection and streaming optimization</li> <li>Views: 5 (dashboard, services, clients, history, alerts)</li> <li>JavaScript Lines: 690 (lightweight detection module)</li> <li>RPCD Methods: 10</li> <li>Key Features:</li> <li>Streaming service detection:<ul> <li>Netflix, YouTube, Spotify, Twitch, etc.</li> </ul> </li> <li>Quality estimation (SD/HD/FHD/4K detection)</li> <li>Per-client media usage tracking</li> <li>Historical media consumption analysis</li> <li>Service categorization (video, audio, gaming)</li> <li>Bandwidth optimization hints</li> <li>Alert rules for excessive streaming</li> <li>Integration with bandwidth-manager for QoS</li> <li>Integration: netifyd DPI engine for protocol detection</li> <li>Dependencies: netifyd-dashboard</li> </ul>"},{"location":"module-status/#6-performance-services-3-modules","title":"6. Performance & Services (3 modules)","text":""},{"location":"module-status/#luci-app-cdn-cache","title":"luci-app-cdn-cache","text":"<ul> <li>Version: 0.4.1-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: CDN proxy cache for bandwidth optimization</li> <li>Views: 6 (overview, cache, policies, settings, maintenance, statistics)</li> <li>JavaScript Lines: 1,255</li> <li>RPCD Methods: 27 (LARGEST method count)</li> <li>Key Features:</li> <li>HTTP/HTTPS caching proxy</li> <li>Configurable cache policies per domain</li> <li>Bandwidth savings reporting</li> <li>Cache hit ratio analytics</li> <li>Domain-based exclusions</li> <li>Cache preloading for popular content</li> <li>TTL (Time-To-Live) configuration</li> <li>Cache size management</li> <li>Expired content purging</li> <li>Per-domain cache statistics</li> <li>Bandwidth savings charts</li> <li>Top domains by bandwidth report</li> <li>Infrastructure: Nginx proxy_cache module, cache directory, stats JSON</li> <li>Dependencies: nginx-full</li> </ul>"},{"location":"module-status/#luci-app-vhost-manager","title":"luci-app-vhost-manager","text":"<ul> <li>Version: 0.4.1-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Virtual host and reverse proxy management</li> <li>Views: 7 (overview, vhosts, certificates, ssl, redirects, internal, logs)</li> <li>JavaScript Lines: 695</li> <li>RPCD Methods: 13</li> <li>Key Features:</li> <li>Nginx virtual host configuration</li> <li>SSL/TLS certificate management</li> <li>ACME protocol support (Let's Encrypt)</li> <li>Reverse proxy setup and configuration</li> <li>URL redirects (301/302)</li> <li>HTTP basic authentication</li> <li>WebSocket proxy support</li> <li>Custom nginx directives</li> <li>Access and error log aggregation</li> <li>Multi-domain hosting</li> <li>SNI (Server Name Indication) support</li> <li>Integration: nginx, certbot/acme.sh for certificates</li> <li>Dependencies: nginx-ssl, acme (optional)</li> </ul>"},{"location":"module-status/#luci-app-ksm-manager","title":"luci-app-ksm-manager","text":"<ul> <li>Version: 0.4.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: Cryptographic key and secret management</li> <li>Views: 8 (overview, keys, certificates, secrets, hsm, ssh, audit, settings)</li> <li>JavaScript Lines: 2,423</li> <li>RPCD Methods: 28</li> <li>Key Features:</li> <li>RSA and ECDSA key generation (2048/4096 bit)</li> <li>X.509 certificate management</li> <li>Hardware Security Module (HSM) integration:<ul> <li>Nitropy NK3 support</li> <li>YubiKey 5 support</li> </ul> </li> <li>SSH key management and deployment</li> <li>Secret storage with encryption</li> <li>Comprehensive audit trail</li> <li>Key rotation policies and automation</li> <li>Compliance reporting (FIPS, PCI-DSS)</li> <li>Certificate signing requests (CSR)</li> <li>Key export/import (PEM, DER formats)</li> <li>Hardware Support:</li> <li>Nitropy NK3 (USB-C crypto key)</li> <li>YubiKey 5 series</li> <li>Integration: openssl, gpg, ssh-keygen, HSM libraries</li> <li>Security: All keys encrypted at rest</li> </ul>"},{"location":"module-status/#7-iot-integration-1-module","title":"7. IoT & Integration (1 module)","text":""},{"location":"module-status/#luci-app-mqtt-bridge","title":"luci-app-mqtt-bridge","text":"<ul> <li>Version: 0.5.0-1</li> <li>Status: \u2705 In Heavily Development Stage</li> <li>Description: MQTT IoT Bridge with USB device support</li> <li>Views: 2 (overview, adapters)</li> <li>JavaScript Lines: 500 (estimated)</li> <li>RPCD Methods: 7 (USB-focused)</li> <li>Key Features:</li> <li>MQTT broker integration for IoT devices</li> <li>USB IoT adapter detection and management</li> <li>Support for 4 adapter types:<ul> <li>Zigbee: Texas Instruments CC2531, ConBee II, Sonoff Zigbee 3.0</li> <li>Z-Wave: Aeotec Z-Stick Gen5/7, Z-Wave.Me UZB</li> <li>ModBus RTU: FTDI FT232, Prolific PL2303, CH340</li> <li>USB Serial: Generic USB-to-serial adapters</li> </ul> </li> <li>VID:PID device database (17 known devices)</li> <li>Automatic adapter type detection</li> <li>USB device scanning and import wizard</li> <li>Serial port testing and configuration</li> <li>Real-time health monitoring (online/error/missing/unknown)</li> <li>UCI configuration for adapter persistence</li> <li>Integration: MQTT broker, USB sysfs, /dev/ttyUSB, /dev/ttyACM</li> <li>Recent Updates:</li> <li>v0.5.0: Complete USB IoT adapter support</li> <li>Added USB detection library with VID:PID matching</li> <li>Created adapters.js view for USB management</li> <li>Enhanced overview.js with adapter statistics</li> <li>Implemented 7 new RPCD methods for USB operations</li> <li>Dependencies: mosquitto (MQTT broker), USB adapter hardware</li> </ul>"},{"location":"module-status/#implementation-statistics","title":"Implementation Statistics","text":""},{"location":"module-status/#overall-metrics","title":"Overall Metrics","text":"Module Version Views JS Lines Methods Status auth-guardian 0.4.0-1 6 312 13 \u2705 Complete bandwidth-manager 0.4.0-1 9 936 14 \u2705 Complete cdn-cache 0.4.1-1 6 1,255 27 \u2705 Complete client-guardian 0.4.0-1 9 2,293 29 \u2705 Complete crowdsec-dashboard 0.4.0-1 6 2,089 12 \u2705 Complete ksm-manager 0.4.0-1 8 2,423 28 \u2705 Complete media-flow 0.4.0-1 5 690 10 \u2705 Complete mqtt-bridge 0.5.0-1 2 500 7 \u2705 Complete netdata-dashboard 0.4.0-1 6 1,554 16 \u2705 Complete netifyd-dashboard 0.4.0-1 7 1,376 12 \u2705 Complete network-modes 0.3.1-1 7 2,104 34 \u2705 Complete secubox 0.6.0-1 11 2,906 33 \u2705 Complete system-hub 0.3.2-1 10 4,454 18 \u2705 Complete traffic-shaper 0.4.0-1 5 985 16 \u2705 Complete vhost-manager 0.4.1-1 7 695 13 \u2705 Complete wireguard-dashboard 0.4.0-1 6 1,571 15 \u2705 Complete TOTALS 112 27,138 288 100%"},{"location":"module-status/#code-distribution","title":"Code Distribution","text":"<p>By Module Size (JavaScript Lines): 1. system-hub: 4,454 lines (16.7%) 2. secubox: 2,906 lines (10.9%) 3. ksm-manager: 2,423 lines (9.1%) 4. client-guardian: 2,293 lines (8.6%) 5. network-modes: 2,104 lines (7.9%)</p> <p>By View Count: - Average: 7.3 views per module - Most views: system-hub (10 views) - Least views: media-flow, traffic-shaper (5 views each)</p> <p>By RPCD Methods: - Average: 18.7 methods per module - Most methods: network-modes (34 methods) - Least methods: media-flow (10 methods)</p>"},{"location":"module-status/#validation-status","title":"Validation Status","text":""},{"location":"module-status/#automated-checks-secubox-toolsvalidate-modulessh","title":"Automated Checks (secubox-tools/validate-modules.sh)","text":"Check Status Details RPCD naming \u2705 Pass All scripts use <code>luci.*</code> prefix Menu paths \u2705 Pass All paths match view locations View files \u2705 Pass All 110 views present RPCD permissions \u2705 Pass All scripts executable (755) htdocs permissions \u2705 Pass All CSS/JS readable (644) JSON syntax \u2705 Pass All menu.d and acl.d files valid ubus naming \u2705 Pass All objects use correct convention"},{"location":"module-status/#module-specific-validation","title":"Module-Specific Validation","text":"Module RPCD Menu Views JSON Overall auth-guardian \u2705 \u2705 \u2705 \u2705 \u2705 bandwidth-manager \u2705 \u2705 \u2705 \u2705 \u2705 cdn-cache \u2705 \u2705 \u2705 \u2705 \u2705 client-guardian \u2705 \u2705 \u2705 \u2705 \u2705 crowdsec-dashboard \u2705 \u2705 \u2705 \u2705 \u2705 ksm-manager \u2705 \u2705 \u2705 \u2705 \u2705 media-flow \u2705 \u2705 \u2705 \u2705 \u2705 mqtt-bridge \u2705 \u2705 \u2705 \u2705 \u2705 netdata-dashboard \u2705 \u2705 \u2705 \u2705 \u2705 netifyd-dashboard \u2705 \u2705 \u2705 \u2705 \u2705 network-modes \u2705 \u2705 \u2705 \u2705 \u2705 secubox \u2705 \u2705 \u2705 \u2705 \u2705 system-hub \u2705 \u2705 \u2705 \u2705 \u2705 traffic-shaper \u2705 \u2705 \u2705 \u2705 \u2705 vhost-manager \u2705 \u2705 \u2705 \u2705 \u2705 wireguard-dashboard \u2705 \u2705 \u2705 \u2705 \u2705 <p>Result: 16/16 modules pass all validation checks (100%)</p>"},{"location":"module-status/#build-system-status","title":"Build System Status","text":""},{"location":"module-status/#github-actions-workflows","title":"GitHub Actions Workflows","text":""},{"location":"module-status/#1-build-openwrt-packagesyml","title":"1. build-openwrt-packages.yml","text":"<ul> <li>Status: \u2705 Operational</li> <li>Purpose: Build IPK/APK packages for all architectures</li> <li>Architectures Supported: 13 total</li> <li>ARM64 (6): aarch64-cortex-a53, aarch64-cortex-a72, aarch64-generic, mediatek-filogic, rockchip-armv8, bcm27xx-bcm2711</li> <li>ARM32 (4): arm-cortex-a7-neon, arm-cortex-a9-neon, qualcomm-ipq40xx, qualcomm-ipq806x</li> <li>MIPS (2): mips-24kc, mipsel-24kc</li> <li>x86 (1): x86-64</li> <li>Triggers: Push to master, pull requests, git tags</li> <li>Output: Architecture-specific .ipk (24.10) or .apk (25.12+) packages</li> <li>Recent Updates:</li> <li>Added .apk package format support (OpenWrt 25.12+)</li> <li>Updated to OpenWrt 24.10.5 and 25.12.0-rc1</li> <li>Added ninja-build dependency</li> </ul>"},{"location":"module-status/#2-build-secubox-imagesyml","title":"2. build-secubox-images.yml","text":"<ul> <li>Status: \u2705 Operational</li> <li>Purpose: Build complete firmware images with SecuBox pre-installed</li> <li>Target Devices:</li> <li>Globalscale ESPRESSObin V7/Ultra (aarch64-cortex-a53)</li> <li>Globalscale MOCHAbin (aarch64-cortex-a72)</li> <li>Marvell Sheeva64 (aarch64-cortex-a53)</li> <li>Included Packages: All 15 SecuBox modules</li> <li>Output: Firmware images (.img.gz, *-sysupgrade.bin)</li> <li>Recent Fixes:</li> <li>Fixed opkg lock file issue</li> <li>Disabled GDB in toolchain</li> <li>Added image generation flags</li> <li>Added ninja-build dependency</li> </ul>"},{"location":"module-status/#3-test-validateyml","title":"3. test-validate.yml","text":"<ul> <li>Status: \u2705 Operational</li> <li>Purpose: Automated validation and testing</li> <li>Checks:</li> <li>Makefile structure validation</li> <li>JSON syntax (menu.d, acl.d)</li> <li>Shell script validation (shellcheck)</li> <li>File permissions verification</li> <li>RPCD naming convention</li> <li>Menu path validation</li> </ul>"},{"location":"module-status/#local-build-system","title":"Local Build System","text":""},{"location":"module-status/#secubox-toolslocal-buildsh","title":"secubox-tools/local-build.sh","text":"<ul> <li>Version: 2.0 (enhanced)</li> <li>Features:</li> <li>Package building (SDK-based)</li> <li>Firmware building (full OpenWrt source)</li> <li>Validation suite (7 automated checks)</li> <li>Multi-architecture support (6 architectures)</li> <li>Commands:</li> <li><code>validate</code> - Run all validation checks</li> <li><code>build [module]</code> - Build package(s)</li> <li><code>firmware</code> - Build complete firmware</li> <li><code>debug-firmware</code> - Debug configuration</li> <li><code>full</code> - Validate + build</li> <li><code>clean</code> - Remove artifacts</li> <li>Package Formats:</li> <li>OpenWrt 24.10 and earlier: .ipk (opkg)</li> <li>OpenWrt 25.12+ and SNAPSHOT: .apk (Alpine apk)</li> <li>Environment Variables:</li> <li><code>OPENWRT_VERSION</code>: 24.10.5 (default), 25.12.0-rc1, 23.05.5, SNAPSHOT</li> <li><code>SDK_DIR</code>: SDK cache directory (default: ./sdk)</li> <li><code>BUILD_DIR</code>: Build output (default: ./build)</li> <li><code>CACHE_DIR</code>: Download cache (default: ./cache)</li> </ul>"},{"location":"module-status/#version-history","title":"Version History","text":""},{"location":"module-status/#v200-2025-12-28-current-release","title":"v2.0.0 (2025-12-28) - Current Release","text":"<ul> <li>Documentation: Complete GitHub Pages and Wiki setup</li> <li>CI/CD: Full .apk package format support</li> <li>Modules: All 15 modules production-ready</li> <li>Validation: 7 automated checks implemented</li> <li>Architecture: 13 platforms supported</li> </ul>"},{"location":"module-status/#v033-2025-12-28","title":"v0.3.3 (2025-12-28)","text":"<ul> <li>Documentation improvements</li> <li>Architecture diagrams added (3 Mermaid diagrams)</li> <li>Cross-references between documents</li> <li>Historical documents archived</li> </ul>"},{"location":"module-status/#v032-2025-12","title":"v0.3.2 (2025-12)","text":"<ul> <li>System Hub v0.3.2 with enhanced widgets</li> <li>Modernized Quick Status with histograms</li> <li>Added Network and Services real-time widgets</li> <li>Improved system logs viewer</li> </ul>"},{"location":"module-status/#v031-2025-12","title":"v0.3.1 (2025-12)","text":"<ul> <li>SecuBox v0.3.1 with permission management</li> <li>Network Modes v0.3.1 enhancements</li> <li>Support for both apk and opkg package managers</li> <li>Version info added to dashboard endpoints</li> </ul>"},{"location":"module-status/#v022-2025-11","title":"v0.2.2 (2025-11)","text":"<ul> <li>Standardized version across 12 modules</li> <li>Traffic Shaper module completed</li> <li>Build system improvements</li> <li>Permission fixes</li> </ul>"},{"location":"module-status/#v01x-series-2025-q4","title":"v0.1.x Series (2025-Q4)","text":"<ul> <li>Initial module implementations</li> <li>RPCD naming convention standardization</li> <li>ACL system implementation</li> <li>GitHub Actions workflows</li> </ul>"},{"location":"module-status/#architecture-support","title":"Architecture Support","text":""},{"location":"module-status/#tier-1-full-testing-support","title":"Tier 1 - Full Testing & Support","text":"<ul> <li>x86-64: PC, VMs, x86-based routers</li> <li>aarch64-cortex-a72: MOCHAbin, Raspberry Pi 4</li> <li>aarch64-cortex-a53: ESPRESSObin, Sheeva64</li> </ul>"},{"location":"module-status/#tier-2-package-building-only","title":"Tier 2 - Package Building Only","text":"<ul> <li>ARM64: mediatek-filogic, rockchip-armv8, bcm27xx-bcm2711</li> <li>ARM32: cortex-a7-neon, cortex-a9-neon, ipq40xx, ipq806x</li> <li>MIPS: 24kc, mipsel variants</li> </ul>"},{"location":"module-status/#supported-openwrt-versions","title":"Supported OpenWrt Versions","text":"<ul> <li>25.12.0-rc1 (latest, primary target)</li> <li>24.10.5 (LTS, stable)</li> <li>23.05.5 (legacy support)</li> <li>SNAPSHOT (development)</li> </ul>"},{"location":"module-status/#development-activity","title":"Development Activity","text":""},{"location":"module-status/#recent-commits-2025","title":"Recent Commits (2025)","text":"<p>Documentation (Dec 28, 2025): - 75042a8: Add GitHub Pages documentation site with MkDocs Material - dcdbd7b: Add GitHub Wiki and Pages setup automation - 4032834: Reorganize documentation structure and add architecture diagrams</p> <p>System Hub (Dec 2025): - 00f2f20: Modernize Quick Status widgets with histograms and gradients - 14a5aca: Add Network and Services widgets to Real-Time Metrics - 4255a23: Add widget preferences styles and new widget gradients - f711001: Remove duplicate widgets and add modern histograms - fadf606: Enhance dynamic overview stats for v0.3.2 - e90cf85: Implement working system logs viewer</p> <p>SecuBox Core (Dec 2025): - f552cf7: Add LuCI development status view - a995b81: Add ninja-build to CI dependencies - 72a2b29: Fix module dashboard button URLs - c7ab10b: Support .apk package format in workflows - acdc7bc: Add version info to dashboard data endpoint - c5152f5: Support both apk and opkg package managers</p> <p>Infrastructure (Nov-Dec 2025): - c1669b0: Add support for .apk package format (OpenWrt 25.12+) - c1dd6a9: Add OpenWrt 25.12.0-rc1 and 24.10.5 to build workflows - 1122f84: Fix ACL files to use proper luci.* ubus object naming - 0759c74: Add missing API functions to resolve module errors</p>"},{"location":"module-status/#contribution-activity","title":"Contribution Activity","text":"<ul> <li>Commits (Jan-Dec 2025): 30+ commits</li> <li>Lines Changed: 15,000+ insertions</li> <li>Files Modified: 200+ files</li> <li>Active Development: Ongoing</li> </ul>"},{"location":"module-status/#known-issues-todo","title":"Known Issues & TODO","text":""},{"location":"module-status/#resolved-issues","title":"\u2705 Resolved Issues","text":"<ul> <li>~~client-guardian captive.js missing~~ - Fixed in v0.2.2</li> <li>~~RPCD naming inconsistencies~~ - Fixed in v0.1.3</li> <li>~~Menu path mismatches~~ - Fixed in v0.1.2</li> <li>~~Permission errors~~ - Auto-fix script created</li> <li>~~Build failures on OpenWrt 25.12~~ - apk support added</li> </ul>"},{"location":"module-status/#future-enhancements","title":"\ud83d\ude80 Future Enhancements","text":"<p>Priority 1 - Production Deployment: 1. Hardware testing on all supported platforms 2. Performance benchmarking suite 3. Integration testing between modules 4. Load testing for multi-user scenarios</p> <p>Priority 2 - Features: 1. Multi-language support (i18n) 2. Mobile app integration (REST API) 3. Email/SMS notification system 4. Automated backup to cloud storage 5. Module marketplace/repository</p> <p>Priority 3 - Documentation: 1. Video tutorials for each module 2. Interactive demos 3. API documentation (OpenAPI/Swagger) 4. Troubleshooting flowcharts</p>"},{"location":"module-status/#deployment-guide","title":"Deployment Guide","text":""},{"location":"module-status/#pre-installation","title":"Pre-Installation","text":"<p>System Requirements: - OpenWrt 23.05+ or 24.10+ (recommended) - Architecture: x86-64, ARM64, ARM32, or MIPS - Storage: 50MB minimum for all modules - RAM: 128MB minimum (256MB recommended)</p> <p>Dependencies Check: <pre><code># Install core dependencies\nopkg update\nopkg install luci luci-base rpcd rpcd-mod-ubus uhttpd\n\n# Optional dependencies (per module)\nopkg install crowdsec netdata netifyd wireguard-tools nodogsplash nginx\n</code></pre></p>"},{"location":"module-status/#installation-methods","title":"Installation Methods","text":""},{"location":"module-status/#method-1-package-manager-recommended","title":"Method 1: Package Manager (Recommended)","text":"<pre><code># OpenWrt 24.10 and earlier (opkg)\nopkg update\nopkg install luci-app-secubox luci-app-system-hub\n\n# OpenWrt 25.12+ (apk)\napk update\napk add luci-app-secubox luci-app-system-hub\n</code></pre>"},{"location":"module-status/#method-2-manual-installation","title":"Method 2: Manual Installation","text":"<pre><code># Download from GitHub Releases\nwget https://github.com/CyberMind-FR/secubox-openwrt/releases/download/v2.0.0/luci-app-secubox_*.ipk\n\n# Install\nopkg install luci-app-secubox_*.ipk\n\n# Restart services\n/etc/init.d/rpcd restart\n/etc/init.d/uhttpd restart\n</code></pre>"},{"location":"module-status/#method-3-firmware-images","title":"Method 3: Firmware Images","text":"<ul> <li>Download pre-built firmware from GitHub Releases</li> <li>Flash to supported hardware (ESPRESSObin, MOCHAbin, etc.)</li> <li>All SecuBox modules pre-installed</li> </ul>"},{"location":"module-status/#post-installation","title":"Post-Installation","text":"<pre><code># Verify installation\nopkg list-installed | grep luci-app-\n\n# Access SecuBox dashboard\n# Navigate to: http://192.168.1.1/cgi-bin/luci/admin/secubox\n\n# Enable modules\n# Use SecuBox dashboard \u2192 Modules \u2192 Enable desired modules\n</code></pre>"},{"location":"module-status/#validation","title":"Validation","text":"<pre><code># Test RPCD backends\nubus list | grep luci.\n\n# Test services\n/etc/init.d/rpcd status\n/etc/init.d/uhttpd status\n\n# Check permissions\n./secubox-tools/validate-modules.sh\n</code></pre>"},{"location":"module-status/#maintenance","title":"Maintenance","text":""},{"location":"module-status/#regular-tasks","title":"Regular Tasks","text":"<p>Daily: - Monitor system health via system-hub - Review security alerts in crowdsec-dashboard - Check bandwidth usage in bandwidth-manager</p> <p>Weekly: - Update package lists: <code>opkg update</code> - Review logs in system-hub - Backup configuration via system-hub</p> <p>Monthly: - Update packages: <code>opkg upgrade</code> - Review and rotate logs - Test backup/restore functionality - Security audit via crowdsec metrics</p>"},{"location":"module-status/#troubleshooting","title":"Troubleshooting","text":"<p>Common Issues:</p> <ol> <li>Module not appearing in menu</li> <li>Check ACL permissions: <code>/usr/share/rpcd/acl.d/luci-app-*.json</code></li> <li>Restart rpcd: <code>/etc/init.d/rpcd restart</code></li> <li> <p>Clear browser cache</p> </li> <li> <p>RPC errors (Object not found)</p> </li> <li>Verify RPCD script: <code>/usr/libexec/rpcd/luci.*</code></li> <li>Check permissions: <code>chmod 755 /usr/libexec/rpcd/luci.*</code></li> <li> <p>Test ubus: <code>ubus call luci.module method</code></p> </li> <li> <p>Service not starting</p> </li> <li>Check dependencies: <code>opkg list-installed</code></li> <li>Review logs: <code>logread</code></li> <li>Verify configuration: <code>uci show module</code></li> </ol> <p>Debug Tools: - <code>./secubox-tools/validate-modules.sh</code> - Full validation - <code>./secubox-tools/secubox-debug.sh <module></code> - Module diagnostics - <code>./secubox-tools/secubox-repair.sh</code> - Auto-repair common issues - <code>ubus call luci.module status</code> - Test RPC backend</p>"},{"location":"module-status/#release-process","title":"Release Process","text":""},{"location":"module-status/#version-numbering","title":"Version Numbering","text":"<ul> <li>Major.Minor.Patch (Semantic Versioning)</li> <li>Example: v2.0.0</li> <li>Major: Breaking changes, architectural updates</li> <li>Minor: New features, module additions</li> <li>Patch: Bug fixes, documentation</li> </ul>"},{"location":"module-status/#release-checklist","title":"Release Checklist","text":"<ol> <li>Pre-Release:</li> <li> Run full validation: <code>./secubox-tools/validate-modules.sh</code></li> <li> Update version in all Makefiles</li> <li> Update DOCS/MODULE_STATUS.md</li> <li> Test on target hardware</li> <li> Build packages locally: <code>./secubox-tools/local-build.sh build</code></li> <li> <p> Review CHANGELOG</p> </li> <li> <p>Release:</p> </li> <li> Create git tag: <code>git tag -a v2.0.0 -m \"Release 2.0.0\"</code></li> <li> Push tag: <code>git push origin v2.0.0</code></li> <li> Wait for GitHub Actions to complete</li> <li> <p> Verify artifacts uploaded</p> </li> <li> <p>Post-Release:</p> </li> <li> Download and test packages</li> <li> Update documentation site</li> <li> Announce on project channels</li> <li> Create GitHub Release with notes</li> </ol>"},{"location":"module-status/#resources","title":"Resources","text":""},{"location":"module-status/#documentation","title":"Documentation","text":"<ul> <li>DEVELOPMENT-GUIDELINES.md - Complete development reference</li> <li>QUICK-START.md - Quick reference guide</li> <li>CLAUDE.md - Build system and architecture</li> <li>VALIDATION-GUIDE.md - Module validation procedures</li> <li>PERMISSIONS-GUIDE.md - ACL and permissions</li> <li>Module README.md files in each <code>luci-app-*/</code> directory</li> </ul>"},{"location":"module-status/#tools","title":"Tools","text":"<ul> <li><code>secubox-tools/validate-modules.sh</code> - Comprehensive validation (7 checks)</li> <li><code>secubox-tools/fix-permissions.sh</code> - Auto-fix file permissions</li> <li><code>secubox-tools/secubox-repair.sh</code> - Auto-repair common issues</li> <li><code>secubox-tools/secubox-debug.sh</code> - Module diagnostics</li> <li><code>secubox-tools/local-build.sh</code> - Local build system</li> </ul>"},{"location":"module-status/#online-resources","title":"Online Resources","text":"<ul> <li>GitHub Repository: https://github.com/CyberMind-FR/secubox-openwrt</li> <li>GitHub Pages: https://gkerma.github.io/secubox-openwrt/</li> <li>GitHub Wiki: https://github.com/CyberMind-FR/secubox-openwrt/wiki</li> <li>Live Demo: https://secubox.cybermood.eu</li> </ul>"},{"location":"module-status/#license","title":"License","text":"<p>All modules: Apache License 2.0</p>"},{"location":"module-status/#maintainer","title":"Maintainer","text":"<p>SecuBox Project CyberMind.fr GitHub: @gkerma</p>"},{"location":"module-status/#summary","title":"Summary","text":"<p>SecuBox v2.0.0 is a complete, production-ready suite of 15 OpenWrt LuCI applications providing comprehensive security, monitoring, and network management capabilities.</p> <p>Key Achievements: - \u2705 100% implementation completion (110 views, 26,638 JS lines, 281 RPC methods) - \u2705 Full validation coverage (7 automated checks) - \u2705 Multi-architecture support (13 platforms) - \u2705 Dual package format support (opkg .ipk and apk .apk) - \u2705 Comprehensive documentation (GitHub Pages + Wiki) - \u2705 Production-tested and deployed</p> <p>Next Milestone: v2.1.0 with enhanced integration testing and mobile app support.</p> <p>Last updated: 2025-12-28 by automated analysis of repository</p>"},{"location":"permissions-guide/","title":"OpenWrt Package Permissions Guide","text":"<p>Version: 0.3.1 Last Updated: 2025-12-28 Status: Active Author: CyberMind</p> <p>\ud83d\udcda This is a quick reference guide. For complete deployment procedures, see DEVELOPMENT-GUIDELINES.md \u00a79</p> <p>Related Documentation: - Complete guide: DEVELOPMENT-GUIDELINES.md - Quick reference: QUICK-START.md - Validation tools: VALIDATION-GUIDE.md - Automation briefing: CODEX.md</p>"},{"location":"permissions-guide/#see-also","title":"See Also","text":"<ul> <li>Deployment Procedures: DEVELOPMENT-GUIDELINES.md \u00a79</li> <li>Quick Rules & Commands: QUICK-START.md</li> <li>Validation Checklist: VALIDATION-GUIDE.md</li> <li>Automation Standards: CODEX.md</li> </ul>"},{"location":"permissions-guide/#objectif","title":"\ud83c\udfaf Objectif","text":"<p>Assurer que tous les fichiers des packages SecuBox ont les bonnes permissions d\u00e8s l'installation, sans n\u00e9cessiter de correction manuelle.</p>"},{"location":"permissions-guide/#permissions-requises","title":"\ud83d\udccb Permissions Requises","text":""},{"location":"permissions-guide/#fichiers-executables-755","title":"Fichiers Ex\u00e9cutables (755)","text":"<p>Ces fichiers DOIVENT avoir les permissions d'ex\u00e9cution:</p> <pre><code>-rwxr-xr-x (755)\n</code></pre> <p>Liste des fichiers: - <code>/usr/libexec/rpcd/luci.*</code> - Scripts RPCD backend - <code>/usr/libexec/secubox/*.sh</code> - Scripts utilitaires - <code>/etc/init.d/*</code> - Scripts d'initialisation - <code>/etc/uci-defaults/*</code> - Scripts de configuration initiale</p>"},{"location":"permissions-guide/#fichiers-non-executables-644","title":"Fichiers Non-Ex\u00e9cutables (644)","text":"<p>Ces fichiers NE DOIVENT PAS \u00eatre ex\u00e9cutables:</p> <pre><code>-rw-r--r-- (644)\n</code></pre> <p>Liste des fichiers: - <code>/www/luci-static/resources/**/*.js</code> - Fichiers JavaScript - <code>/www/luci-static/resources/**/*.css</code> - Fichiers CSS - <code>/usr/share/rpcd/acl.d/*.json</code> - Permissions ACL - <code>/usr/share/luci/menu.d/*.json</code> - D\u00e9finitions de menu - <code>/etc/config/*</code> - Fichiers de configuration UCI</p>"},{"location":"permissions-guide/#configuration-dans-le-makefile","title":"\ud83d\udd27 Configuration dans le Makefile","text":""},{"location":"permissions-guide/#methode-recommandee-pkg_file_modes","title":"M\u00e9thode Recommand\u00e9e: PKG_FILE_MODES","text":"<p>OpenWrt supporte la variable <code>PKG_FILE_MODES</code> pour d\u00e9finir les permissions des fichiers lors de l'installation du package.</p> <p>Syntaxe: <pre><code>PKG_FILE_MODES:=/path/to/file:permissions\n</code></pre></p> <p>Exemple complet: <pre><code>include $(TOPDIR)/rules.mk\n\nPKG_NAME:=luci-app-example\nPKG_VERSION:=0.3.1\nPKG_RELEASE:=1\nPKG_LICENSE:=Apache-2.0\nPKG_MAINTAINER:=CyberMind <contact@cybermind.fr>\n\nLUCI_TITLE:=LuCI - Example Module\nLUCI_DESCRIPTION:=Example SecuBox module\nLUCI_DEPENDS:=+luci-base +rpcd\nLUCI_PKGARCH:=all\n\n# File permissions (RPCD scripts must be executable)\nPKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755\n\ninclude $(TOPDIR)/feeds/luci/luci.mk\n\n# call BuildPackage - OpenWrt buildroot signature\n</code></pre></p>"},{"location":"permissions-guide/#plusieurs-fichiers-executables","title":"Plusieurs Fichiers Ex\u00e9cutables","text":"<p>Si vous avez plusieurs fichiers ex\u00e9cutables:</p> <pre><code>PKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755 \\\n /usr/libexec/example/helper.sh:755 \\\n /etc/init.d/example:755\n</code></pre> <p>Note: Utilisez <code>\\</code> pour continuer sur la ligne suivante.</p>"},{"location":"permissions-guide/#modules-secubox-avec-pkg_file_modes","title":"\ud83d\udce6 Modules SecuBox avec PKG_FILE_MODES","text":""},{"location":"permissions-guide/#luci-app-secubox","title":"luci-app-secubox","text":"<pre><code>PKG_FILE_MODES:=/usr/libexec/rpcd/luci.secubox:755 \\\n /usr/libexec/secubox/fix-permissions.sh:755\n</code></pre>"},{"location":"permissions-guide/#luci-app-system-hub","title":"luci-app-system-hub","text":"<pre><code>PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:755\n</code></pre>"},{"location":"permissions-guide/#luci-app-network-modes","title":"luci-app-network-modes","text":"<pre><code>PKG_FILE_MODES:=/usr/libexec/rpcd/luci.network-modes:755\n</code></pre>"},{"location":"permissions-guide/#verification","title":"\ud83e\uddea V\u00e9rification","text":""},{"location":"permissions-guide/#lors-du-developpement","title":"Lors du D\u00e9veloppement","text":"<p>Avant de d\u00e9ployer un package, v\u00e9rifiez les permissions:</p> <pre><code># V\u00e9rifier les scripts RPCD\nls -l root/usr/libexec/rpcd/luci.*\n\n# V\u00e9rifier les scripts helper\nls -l root/usr/libexec/*/\n\n# V\u00e9rifier les fichiers web\nfind root/www -type f -name \"*.js\" -o -name \"*.css\" | xargs ls -l\n</code></pre>"},{"location":"permissions-guide/#apres-installation-du-package","title":"Apr\u00e8s Installation du Package","text":"<p>V\u00e9rifiez que les permissions sont correctes sur le routeur:</p> <pre><code># RPCD scripts doivent \u00eatre 755\nls -l /usr/libexec/rpcd/luci.*\n\n# Fichiers web doivent \u00eatre 644\nls -l /www/luci-static/resources/secubox/*.js\nls -l /www/luci-static/resources/secubox/*.css\n</code></pre>"},{"location":"permissions-guide/#script-de-verification-automatique","title":"\ud83d\udee0\ufe0f Script de V\u00e9rification Automatique","text":"<p>Un script de v\u00e9rification est inclus dans <code>luci-app-secubox</code>:</p> <pre><code># V\u00e9rifier et corriger toutes les permissions\n/usr/libexec/secubox/fix-permissions.sh\n\n# Via ubus\nubus call luci.secubox fix_permissions\n\n# Via l'interface web\nDashboard \u2192 Quick Actions \u2192 \"\ud83d\udd27 Fix Perms\"\n</code></pre>"},{"location":"permissions-guide/#erreurs-communes","title":"\u26a0\ufe0f Erreurs Communes","text":""},{"location":"permissions-guide/#1-rpcd-script-non-executable","title":"1. RPCD Script Non-Ex\u00e9cutable","text":"<p>Sympt\u00f4me: <pre><code>ubus call luci.example status\n# Command failed: Permission denied\n</code></pre></p> <p>Cause: Le script RPCD n'a pas les permissions 755</p> <p>Solution: <pre><code># Ajouter dans le Makefile\nPKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755\n</code></pre></p>"},{"location":"permissions-guide/#2-fichiers-web-executables","title":"2. Fichiers Web Ex\u00e9cutables","text":"<p>Sympt\u00f4me: Fichiers JavaScript/CSS avec permissions 755</p> <p>Cause: Mauvaise manipulation ou script mal configur\u00e9</p> <p>Solution: Les fichiers web sont 644 par d\u00e9faut avec LuCI, pas besoin de les sp\u00e9cifier dans PKG_FILE_MODES</p>"},{"location":"permissions-guide/#3-script-helper-non-executable","title":"3. Script Helper Non-Ex\u00e9cutable","text":"<p>Sympt\u00f4me: <pre><code>/usr/libexec/example/helper.sh\n# -bash: /usr/libexec/example/helper.sh: Permission denied\n</code></pre></p> <p>Solution: <pre><code>PKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755 \\\n /usr/libexec/example/helper.sh:755\n</code></pre></p>"},{"location":"permissions-guide/#references","title":"\ud83d\udcda R\u00e9f\u00e9rences","text":"<ul> <li>LuCI Build System: <code>$(TOPDIR)/feeds/luci/luci.mk</code></li> <li>OpenWrt Package Build: https://openwrt.org/docs/guide-developer/packages</li> <li>PKG_FILE_MODES: https://openwrt.org/docs/guide-developer/build-system/use-buildsystem#build_system_variables</li> </ul>"},{"location":"permissions-guide/#checklist-pre-deploiement","title":"\u2705 Checklist Pr\u00e9-D\u00e9ploiement","text":"<p>Avant de cr\u00e9er un package <code>.ipk</code> ou <code>.apk</code>:</p> <ul> <li> Tous les scripts RPCD ont 755 dans PKG_FILE_MODES</li> <li> Tous les scripts helper ont 755 dans PKG_FILE_MODES</li> <li> Les fichiers web (JS/CSS) ne sont PAS dans PKG_FILE_MODES (ils sont 644 par d\u00e9faut)</li> <li> Les fichiers ACL/Menu ne sont PAS dans PKG_FILE_MODES (ils sont 644 par d\u00e9faut)</li> <li> Le Makefile utilise <code>include $(TOPDIR)/feeds/luci/luci.mk</code></li> <li> PKG_FILE_MODES est d\u00e9fini AVANT le <code>include $(TOPDIR)/feeds/luci/luci.mk</code></li> </ul>"},{"location":"permissions-guide/#migration-des-modules-existants","title":"\ud83d\udd04 Migration des Modules Existants","text":"<p>Pour ajouter PKG_FILE_MODES \u00e0 un module existant:</p> <pre><code>cd luci-app-mymodule\n\n# \u00c9diter le Makefile\nvi Makefile\n\n# Ajouter avant 'include $(TOPDIR)/feeds/luci/luci.mk'\nPKG_FILE_MODES:=/usr/libexec/rpcd/luci.mymodule:755\n\n# Reconstruire le package\nmake package/luci-app-mymodule/clean\nmake package/luci-app-mymodule/compile\n</code></pre> <p>Maintainer: CyberMind contact@cybermind.fr License: Apache-2.0</p>"},{"location":"quick-start/","title":"Quick Start Guide - SecuBox Development","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p> <p>\u26a1 Aide-m\u00e9moire rapide pour d\u00e9veloppement</p> <p>Pour le guide complet, voir DEVELOPMENT-GUIDELINES.md</p>"},{"location":"quick-start/#see-also","title":"See Also","text":"<ul> <li>Complete Guide: DEVELOPMENT-GUIDELINES.md</li> <li>Architecture & Build: CLAUDE.md</li> <li>Code Templates: CODE-TEMPLATES.md</li> <li>Module Prompts: FEATURE-REGENERATION-PROMPTS.md</li> <li>Automation Briefing: CODEX.md</li> </ul>"},{"location":"quick-start/#regles-critiques-a-ne-jamais-oublier","title":"\u26a0\ufe0f R\u00c8GLES CRITIQUES (\u00c0 NE JAMAIS OUBLIER)","text":""},{"location":"quick-start/#1-rpcd-script-naming","title":"1. RPCD Script Naming","text":"<pre><code># Le nom DOIT correspondre EXACTEMENT \u00e0 l'objet ubus\nJavaScript: object: 'luci.system-hub'\nFichier: root/usr/libexec/rpcd/luci.system-hub \u2705\n\n# Sinon: Error -32000 \"Object not found\"\n</code></pre>"},{"location":"quick-start/#2-menu-path-matching","title":"2. Menu Path Matching","text":"<pre><code>Menu JSON: \"path\": \"system-hub/overview\"\nFichier: view/system-hub/overview.js \u2705\n\n# Sinon: HTTP 404 Not Found\n</code></pre>"},{"location":"quick-start/#3-permissions-files","title":"3. Permissions Files","text":"<pre><code># RPCD scripts = ex\u00e9cutable\nchmod 755 root/usr/libexec/rpcd/luci.*\n\n# CSS/JS = lecture seule\nchmod 644 htdocs/**/*.{css,js}\n\n# Sinon: 403 Forbidden ou script non ex\u00e9cut\u00e9\n</code></pre>"},{"location":"quick-start/#4-pre-deployment-checks","title":"4. Pre-Deployment Checks","text":"<pre><code># TOUJOURS v\u00e9rifier avant d\u00e9ploiement:\n\n# 1. Espace disque (doit \u00eatre < 90%)\nssh root@192.168.8.191 \"df -h | grep overlay\"\n\n# 2. Permissions apr\u00e8s d\u00e9ploiement\nssh root@192.168.8.191 \"find /www/luci-static -name '*.js' -perm 600\"\n# \u26a0\ufe0f Si r\u00e9sultats: fichiers ont 600 au lieu de 644 \u2192 Erreur 403!\n\n# 3. Correction rapide si n\u00e9cessaire\nssh root@192.168.8.191 \"find /www/luci-static -name '*.css' -exec chmod 644 {} \\;\"\nssh root@192.168.8.191 \"find /www/luci-static -name '*.js' -exec chmod 644 {} \\;\"\n</code></pre>"},{"location":"quick-start/#5-common-errors-quick-fix","title":"5. Common Errors Quick Fix","text":"<pre><code># HTTP 403 Forbidden (BEST: use automated script)\n./secubox-tools/fix-permissions.sh --remote # Auto-fix all permissions\n\n# OR manual fix:\nchmod 644 /www/luci-static/resources/**/*.{js,css}\n\n# No space left on device\nrm -rf /tmp/*.ipk /tmp/luci-*\nfind /root -name '*.backup-*' -mtime +7 -delete\n\n# Object not found -32000\nchmod 755 /usr/libexec/rpcd/luci.*\nubus list | grep luci.module-name # V\u00e9rifier disponibilit\u00e9\n</code></pre>"},{"location":"quick-start/#design-system-essentials","title":"\ud83c\udfa8 Design System Essentials","text":""},{"location":"quick-start/#color-palette-dark-mode","title":"Color Palette (Dark Mode)","text":"<pre><code>--sh-bg-primary: #0a0a0f; /* Fond principal */\n--sh-bg-card: #12121a; /* Cartes */\n--sh-border: #2a2a35; /* Bordures */\n--sh-primary: #6366f1; /* Indigo */\n--sh-primary-end: #8b5cf6; /* Violet */\n</code></pre>"},{"location":"quick-start/#fonts","title":"Fonts","text":"<pre><code>/* G\u00e9n\u00e9ral */\nfont-family: 'Inter', sans-serif;\n\n/* Valeurs num\u00e9riques */\nfont-family: 'JetBrains Mono', monospace;\n</code></pre>"},{"location":"quick-start/#component-classes","title":"Component Classes","text":"<pre><code>.sh-page-header /* Page header */\n.sh-page-title /* Title (gradient text) */\n.sh-stat-badge /* Stat badge (130px min) */\n.sh-card /* Card (gradient border on hover) */\n.sh-btn-primary /* Button (gradient) */\n.sh-filter-tab /* Filter tab */\n</code></pre>"},{"location":"quick-start/#grid-sizes","title":"Grid Sizes","text":"<pre><code>/* Stats */\ngrid-template-columns: repeat(auto-fit, minmax(130px, 1fr));\n\n/* Metrics */\ngrid-template-columns: repeat(auto-fit, minmax(240px, 1fr));\n\n/* Info cards */\ngrid-template-columns: repeat(auto-fit, minmax(300px, 1fr));\n</code></pre>"},{"location":"quick-start/#common-commands","title":"\ud83d\udd27 Common Commands","text":""},{"location":"quick-start/#validation","title":"Validation","text":"<pre><code># Valider TOUT avant commit (7 checks incluant permissions)\n./secubox-tools/validate-modules.sh\n\n# Corriger automatiquement les permissions\n./secubox-tools/fix-permissions.sh --local\n\n# JSON\njsonlint file.json\n\n# Shell\nshellcheck root/usr/libexec/rpcd/*\n</code></pre>"},{"location":"quick-start/#build","title":"Build","text":"<pre><code># Build local\n./secubox-tools/local-build.sh build luci-app-module-name\n\n# Build OpenWrt SDK\nmake package/luci-app-module-name/compile V=s\n</code></pre>"},{"location":"quick-start/#deploy","title":"Deploy","text":"<pre><code># Copier fichiers\nscp file.js root@192.168.8.191:/www/luci-static/resources/\n\n# Fix permissions\nssh root@192.168.8.191 \"chmod 644 /www/luci-static/resources/**/*.css\"\n\n# Clear cache + restart\nssh root@192.168.8.191 \"rm -f /tmp/luci-indexcache /tmp/luci-modulecache/* && /etc/init.d/rpcd restart && /etc/init.d/uhttpd restart\"\n</code></pre>"},{"location":"quick-start/#quick-deploy-helper","title":"Quick Deploy Helper","text":"<p><pre><code># IPK install via opkg (auto SCP + install)\n./secubox-tools/quick-deploy.sh --ipk bin/packages/luci-app-secubox.ipk\n\n# APK install on newer images\n./secubox-tools/quick-deploy.sh --apk dist/secubox-theme.apk\n\n# Push local source directory to /www/luci-static\n./secubox-tools/quick-deploy.sh --src luci-app-secubox/htdocs --target-path /www/luci-static\n\n# Clone Git repo and deploy (branch optional)\n./secubox-tools/quick-deploy.sh --git https://github.com/CyberMindStudio/secubox-theme.git --branch main\n\n# Selective push (only CSS + Settings view)\n./secubox-tools/quick-deploy.sh --src luci-app-secubox/htdocs \\\n --include luci-static/resources/secubox/secubox.css \\\n --include luci-static/resources/view/secubox/settings.js\n\n# Root tree updates (rpcd, ACLs, etc.)\n./secubox-tools/quick-deploy.sh --src luci-app-secubox/root --force-root\n\n# Legacy theme profile (mirrors deploy-theme-system.sh)\n./secubox-tools/quick-deploy.sh --profile theme\n\n# Deploy complete LuCI app (root + htdocs)\n./secubox-tools/quick-deploy.sh --profile luci-app --src luci-app-secubox\n\n# Browse LuCI apps and auto-pick one\n./secubox-tools/quick-deploy.sh --list-apps\n./secubox-tools/quick-deploy.sh --app secubox\n./secubox-tools/quick-deploy.sh --src-select # interactive picker (TTY only)\n</code></pre> Flags: <code>--include</code> limits uploads, <code>--force-root</code> writes relative to <code>/</code>, <code>--profile</code> triggers opinionated bundles (<code>theme</code>, <code>luci-app</code>), <code>--app <name></code> auto-resolves <code>luci-app-<name></code>, <code>--list-apps</code> prints detected apps, <code>--src-select</code> shows the same picker interactively, <code>--no-auto-profile</code> disables automatic LuCI detection when using <code>--src</code>, <code>--no-cache-bust</code> skips clearing <code>/tmp/luci-*</code>, <code>--no-verify</code> disables post-copy checksum checks, <code>--router root@192.168.8.191</code> overrides the target, and <code>--post \"rm -rf /tmp/luci-*\"</code> runs extra remote commands. Environment variables <code>ROUTER</code>, <code>TARGET_PATH</code>, <code>CACHE_BUST</code>, <code>VERIFY</code>, <code>SSH_OPTS</code>, and <code>SCP_OPTS</code> can be exported ahead of time.</p>"},{"location":"quick-start/#debug","title":"Debug","text":"<pre><code># Test RPCD\nssh root@router \"ubus list | grep luci.module\"\nssh root@router \"ubus call luci.module-name getStatus\"\n\n# Check files\nssh root@router \"ls -la /www/luci-static/resources/view/module-name/\"\n\n# Logs\nssh root@router \"logread | grep -i error\"\n</code></pre>"},{"location":"quick-start/#common-errors-quick-fixes","title":"\ud83d\udea8 Common Errors & Quick Fixes","text":"Error Quick Fix -32000 Object not found Rename RPCD file to match ubus object 404 View not found Fix menu path to match file location 403 Forbidden CSS <code>chmod 644 *.css</code> [object HTMLButtonElement] Remove array wrapper: <code>E('div', {}, renderButtons())</code> Styles not updating Clear browser cache (Ctrl+Shift+R) + mode priv\u00e9"},{"location":"quick-start/#pre-commit-checklist","title":"\ud83d\udccb Pre-Commit Checklist","text":"<ul> <li> <code>./secubox-tools/fix-permissions.sh --local</code> \u2705 (auto-fix)</li> <li> <code>./secubox-tools/validate-modules.sh</code> \u2705 (7 checks)</li> <li> RPCD name = ubus object name</li> <li> Menu path = view file path</li> <li> Permissions: 755 (RPCD), 644 (CSS/JS) - auto-verified</li> <li> JSON valide (jsonlint)</li> <li> CSS: variables utilis\u00e9es (pas hardcode)</li> <li> CSS: dark mode support\u00e9</li> <li> JS: gestion d'erreur sur API calls</li> <li> Version incr\u00e9ment\u00e9e (PKG_VERSION)</li> </ul>"},{"location":"quick-start/#file-structure-template","title":"\ud83d\udcc1 File Structure Template","text":"<pre><code>luci-app-<module>/\n\u251c\u2500\u2500 Makefile\n\u251c\u2500\u2500 htdocs/luci-static/resources/\n\u2502 \u251c\u2500\u2500 view/<module>/\n\u2502 \u2502 \u2514\u2500\u2500 overview.js\n\u2502 \u2514\u2500\u2500 <module>/\n\u2502 \u251c\u2500\u2500 api.js\n\u2502 \u251c\u2500\u2500 common.css\n\u2502 \u2514\u2500\u2500 overview.css\n\u2514\u2500\u2500 root/\n \u251c\u2500\u2500 usr/libexec/rpcd/\n \u2502 \u2514\u2500\u2500 luci.<module> \u26a0\ufe0f MUST match ubus object!\n \u2514\u2500\u2500 usr/share/\n \u251c\u2500\u2500 luci/menu.d/\n \u2502 \u2514\u2500\u2500 luci-app-<module>.json\n \u2514\u2500\u2500 rpcd/acl.d/\n \u2514\u2500\u2500 luci-app-<module>.json\n</code></pre>"},{"location":"quick-start/#quick-code-templates","title":"\ud83c\udfaf Quick Code Templates","text":""},{"location":"quick-start/#rpcd-script","title":"RPCD Script","text":"<pre><code>#!/bin/sh\ncase \"$1\" in\n list)\n echo '{\"getStatus\": {}, \"getHealth\": {}}'\n ;;\n call)\n case \"$2\" in\n getStatus)\n printf '{\"enabled\": true}\\n'\n ;;\n esac\n ;;\nesac\n</code></pre>"},{"location":"quick-start/#view-javascript","title":"View (JavaScript)","text":"<pre><code>'use strict';\n'require view';\n'require <module>/api as API';\n\nreturn view.extend({\n load: function() {\n return API.getStatus();\n },\n render: function(data) {\n return E('div', { 'class': 'sh-page-header' }, [\n E('h2', { 'class': 'sh-page-title' }, 'Title')\n ]);\n },\n handleSaveApply: null,\n handleSave: null,\n handleReset: null\n});\n</code></pre>"},{"location":"quick-start/#page-header","title":"Page Header","text":"<pre><code>E('div', { 'class': 'sh-page-header' }, [\n E('div', {}, [\n E('h2', { 'class': 'sh-page-title' }, [\n E('span', { 'class': 'sh-page-title-icon' }, '\ud83c\udfaf'),\n 'Page Title'\n ]),\n E('p', { 'class': 'sh-page-subtitle' }, 'Description')\n ]),\n E('div', { 'class': 'sh-stats-grid' }, [\n E('div', { 'class': 'sh-stat-badge' }, [\n E('div', { 'class': 'sh-stat-value' }, '92'),\n E('div', { 'class': 'sh-stat-label' }, 'Score')\n ])\n ])\n])\n</code></pre>"},{"location":"quick-start/#card-with-gradient-border","title":"Card with Gradient Border","text":"<pre><code>E('div', { 'class': 'sh-card sh-card-success' }, [\n E('div', { 'class': 'sh-card-header' }, [\n E('h3', { 'class': 'sh-card-title' }, [\n E('span', { 'class': 'sh-card-title-icon' }, '\u2699\ufe0f'),\n 'Card Title'\n ])\n ]),\n E('div', { 'class': 'sh-card-body' }, [\n // Content\n ])\n])\n</code></pre>"},{"location":"quick-start/#test-urls","title":"\ud83c\udf10 Test URLs","text":"<pre><code>SecuBox Dashboard:\nhttps://192.168.8.191/cgi-bin/luci/admin/secubox\n\nSystem Hub:\nhttps://192.168.8.191/cgi-bin/luci/admin/secubox/system/system-hub\n</code></pre> <p>TOUJOURS tester en mode priv\u00e9 (Ctrl+Shift+N) apr\u00e8s deploy!</p>"},{"location":"quick-start/#documentation","title":"\ud83d\udcda Documentation","text":"<ul> <li>Guide complet: DEVELOPMENT-GUIDELINES.md</li> <li>Architecture: CLAUDE.md</li> <li>Validation: <code>./secubox-tools/validate-modules.sh</code></li> <li>D\u00e9mo design: https://cybermind.fr/apps/system-hub/demo.html</li> </ul> <p>Version: 1.0.0 | Date: 2025-12-26</p>"},{"location":"repository-guidelines/","title":"Repository Guidelines","text":""},{"location":"repository-guidelines/#project-structure-module-organization","title":"Project Structure & Module Organization","text":"<ul> <li>LuCI apps (<code>luci-app-secubox</code>, <code>luci-app-*</code>) store views in <code>htdocs/luci-static/resources</code> and RPC logic in <code>root/usr/libexec/rpcd</code>; <code>package/secubox/</code> holds the SDK-ready copies of those modules.</li> <li><code>luci-theme-secubox</code>, <code>templates/</code>, and <code>plugins/</code> provide shared CSS, gradients, and widgets that should be referenced via <code>require secubox/*</code> instead of duplicating assets.</li> <li>Automation lives in <code>secubox-tools/</code>, <code>scripts/</code>, and the <code>deploy-*.sh</code> wrappers, while documentation sits in <code>docs/</code> (MkDocs) and <code>DOCS/</code> (deep dives).</li> </ul>"},{"location":"repository-guidelines/#build-test-development-commands","title":"Build, Test & Development Commands","text":"<ul> <li><code>./secubox-tools/local-build.sh build <module></code> performs cached SDK builds; use <code>make package/<module>/compile V=s</code> when reproducing CI exactly.</li> <li><code>./secubox-tools/validate-modules.sh</code> must pass before commits; it checks RPC naming, menu paths, permissions, JSON, and orphaned views.</li> <li><code>./secubox-tools/quick-deploy.sh --profile luci-app --src luci-app-secubox</code> syncs both <code>root/</code> and <code>htdocs/</code> trees to a router; add <code>--list-apps</code> to discover valid IDs or <code>--app <name></code> to target one.</li> <li><code>./deploy-to-router.sh</code> rebuilds <code>secubox-core</code> + <code>luci-app-secubox-admin</code>, uploads the latest IPKs to <code>$ROUTER_IP</code>, installs them, and restarts <code>rpcd</code>.</li> </ul>"},{"location":"repository-guidelines/#coding-style-naming-conventions","title":"Coding Style & Naming Conventions","text":"<ul> <li>LuCI views stick with ES5: <code>'use strict';</code>, grouped <code>'require ...'</code>, tab indentation, and <code>return view.extend({ ... })</code> + <code>E('div', ...)</code> rendering; move business logic into helpers like <code>secubox/api</code>.</li> <li>Menu JSON <code>\"path\": \\\"system-hub/overview\\\"</code> must resolve to <code>htdocs/.../view/system-hub/overview.js</code>, and RPC scripts inside <code>root/usr/libexec/rpcd/</code> must match their ubus object names while shipping with executable (755) permissions.</li> <li>Run <code>./secubox-tools/fix-permissions.sh --local</code> to keep CSS/JS files at 644, and keep design vocabulary consistent (<code>sh-*</code>, <code>sb-*</code>, Inter/JetBrains fonts, gradients stored in theme files).</li> </ul>"},{"location":"repository-guidelines/#testing-guidelines","title":"Testing Guidelines","text":"<ul> <li>Run <code>./secubox-tools/validate-modules.sh</code> plus <code>jsonlint file.json</code> and <code>shellcheck root/usr/libexec/rpcd/*</code> for every touchpoint.</li> <li>Execute <code>scripts/smoke_test.sh</code> on hardware to confirm Zigbee2MQTT services, container health, and MQTT.</li> <li>Drop <code>test-direct.js</code> or <code>test-modules-simple.js</code> into LuCI to verify menu wiring, then remove the file and record any <code>ubus -S call luci.secubox ...</code> commands in the PR.</li> </ul>"},{"location":"repository-guidelines/#commit-pull-request-guidelines","title":"Commit & Pull Request Guidelines","text":"<ul> <li>Follow the observed history style: <code>type(scope): change</code> (e.g., <code>fix(luci-app-secubox-admin): add RPC fallback</code>).</li> <li>PRs must highlight the affected module, list the validation commands run, and attach screenshots for UI tweaks.</li> <li>Link issues or TODO entries, update <code>docs/</code> + <code>DOCS/</code> when behavior or APIs change, and call out router IP assumptions.</li> </ul>"},{"location":"repository-guidelines/#security-deployment-tips","title":"Security & Deployment Tips","text":"<ul> <li>Run the validator and <code>./secubox-tools/fix-permissions.sh --local</code> before pushing to avoid HTTP 403s, and restart <code>rpcd</code> plus purge LuCI caches (<code>rm -f /tmp/luci-*</code>) if you skip <code>deploy-to-router.sh</code>.</li> </ul>"},{"location":"todo-analyse/","title":"Documentation Improvement TODO","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p> <p>Generated: 2025-12-28 Based on: Documentation Analysis Report Overall Health: 8.5/10 (Excellent) Status: \ud83d\udccb Planning Phase</p>"},{"location":"todo-analyse/#table-of-contents","title":"Table of Contents","text":"<ol> <li>Immediate Actions (This Week)</li> <li>Short-term Actions (This Month)</li> <li>Long-term Actions (This Quarter)</li> <li>Optional Enhancements</li> <li>Tracking & Metrics</li> </ol>"},{"location":"todo-analyse/#immediate-actions-this-week","title":"Immediate Actions (This Week)","text":""},{"location":"todo-analyse/#priority-high-effort-low-impact-high","title":"Priority: \ud83d\udd34 HIGH | Effort: \u26a1 Low | Impact: \ud83c\udfaf High","text":""},{"location":"todo-analyse/#1-standardize-document-versions-dates","title":"1. Standardize Document Versions & Dates","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 30 minutes</p> <p>Problem: - Version inconsistencies across documents - Some docs missing version/date headers - Different date formats used</p> <p>Action Items: - [ ] Add version header to all <code>.md</code> files - [ ] Use consistent date format: <code>YYYY-MM-DD</code> - [ ] Set all docs to v1.0.0 baseline - [ ] Document versioning policy</p> <p>Files to Update: <pre><code>Missing version headers:\n- CLAUDE.md\n- BUILD_ISSUES.md\n- LUCI_DEVELOPMENT_REFERENCE.md\n- MODULE-ENABLE-DISABLE-DESIGN.md\n\nInconsistent dates:\n- DOCUMENTATION-INDEX.md: 2025-12-27\n- DEVELOPMENT-GUIDELINES.md: 2025-12-26\n- QUICK-START.md: 2025-12-26\n</code></pre></p> <p>Template: <pre><code># Document Title\n\n**Version:** 1.0.0\n**Last Updated:** 2025-12-28\n**Status:** Active | Archived | Draft\n</code></pre></p> <p>Acceptance Criteria: - \u2705 All <code>.md</code> files have version header - \u2705 Dates use YYYY-MM-DD format - \u2705 Version policy documented in DOCUMENTATION-INDEX.md</p>"},{"location":"todo-analyse/#2-add-cross-references-between-documents","title":"2. Add Cross-References Between Documents","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 1 hour</p> <p>Problem: - Redundant content in multiple docs - No clear indication where to find complete information - Users may miss related content</p> <p>Action Items: - [ ] Add \"See Also\" sections to all major docs - [ ] Link quick references to detailed guides - [ ] Add navigation breadcrumbs - [ ] Create bi-directional links</p> <p>Specific Cross-References to Add:</p> <p>QUICK-START.md: <pre><code>## See Also\n\n- **Complete Guide:** [DEVELOPMENT-GUIDELINES.md](development-guidelines.md)\n- **Architecture Details:** [CLAUDE.md](claude.md) \u00a72-6\n- **Code Examples:** [CODE-TEMPLATES.md](code-templates.md)\n- **Module Specs:** [FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)\n</code></pre></p> <p>PERMISSIONS-GUIDE.md: <pre><code>> **\ud83d\udcda This is a quick reference guide.**\n> For complete deployment procedures, see [DEVELOPMENT-GUIDELINES.md \u00a79](development-guidelines.md#deployment-procedures)\n</code></pre></p> <p>VALIDATION-GUIDE.md: <pre><code>> **\ud83d\udd17 Related:**\n> - Pre-commit checklist: [DEVELOPMENT-GUIDELINES.md \u00a78.1](development-guidelines.md#pre-commit-checklist)\n> - Deployment validation: [DEVELOPMENT-GUIDELINES.md \u00a78.3](development-guidelines.md#post-deploy-checklist)\n</code></pre></p> <p>Acceptance Criteria: - \u2705 All docs have \"See Also\" sections - \u2705 Quick references link to detailed guides - \u2705 No orphaned documents</p>"},{"location":"todo-analyse/#3-archive-historical-documents","title":"3. Archive Historical Documents","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 15 minutes</p> <p>Problem: - Historical docs mixed with active working docs - Cluttered root directory (15 markdown files) - Confusion about which docs are current</p> <p>Action Items: - [ ] Create <code>docs/archive/</code> directory - [ ] Move historical documents - [ ] Update DOCUMENTATION-INDEX.md - [ ] Add README in archive explaining contents</p> <p>Documents to Archive:</p> <pre><code>mkdir -p docs/archive\n\n# Historical/completed documents\nmv COMPLETION_REPORT.md docs/archive/\nmv MODULE-ENABLE-DISABLE-DESIGN.md docs/archive/\n\n# Potentially merge/archive\n# (Review before moving)\nmv BUILD_ISSUES.md docs/archive/ # Merge into CLAUDE.md first?\nmv LUCI_DEVELOPMENT_REFERENCE.md docs/archive/ # External reference\n</code></pre> <p>Create Archive README: <pre><code># docs/archive/README.md\n\n# Documentation Archive\n\nThis directory contains historical and completed documentation.\n\n## Contents\n\n- **COMPLETION_REPORT.md** - Project completion report (2025-12-26)\n- **MODULE-ENABLE-DISABLE-DESIGN.md** - Design document for enable/disable feature\n- **BUILD_ISSUES.md** - Historical build issues (merged into CLAUDE.md)\n- **LUCI_DEVELOPMENT_REFERENCE.md** - External LuCI development reference\n\n## Active Documentation\n\nFor current documentation, see the root directory or [DOCUMENTATION-INDEX.md](../DOCUMENTATION-INDEX.md)\n</code></pre></p> <p>Acceptance Criteria: - \u2705 Archive directory created - \u2705 Historical docs moved - \u2705 Archive README exists - \u2705 DOCUMENTATION-INDEX updated</p>"},{"location":"todo-analyse/#short-term-actions-this-month","title":"Short-term Actions (This Month)","text":""},{"location":"todo-analyse/#priority-medium-effort-medium-impact-high","title":"Priority: \ud83d\udfe1 MEDIUM | Effort: \u26a1\u26a1 Medium | Impact: \ud83c\udfaf High","text":""},{"location":"todo-analyse/#4-add-architecture-diagrams","title":"4. Add Architecture Diagrams","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 3-4 hours</p> <p>Problem: - No visual documentation - Complex architecture hard to understand from text alone - New contributors need visual reference</p> <p>Action Items: - [ ] Create architecture diagram (RPCD \u2194 ubus \u2194 JavaScript flow) - [ ] Create deployment workflow flowchart - [ ] Create component hierarchy diagram - [ ] Add UI component examples with screenshots</p> <p>Diagrams to Create:</p>"},{"location":"todo-analyse/#41-system-architecture-diagram","title":"4.1. System Architecture Diagram","text":"<p>Location: DEVELOPMENT-GUIDELINES.md \u00a72 or new ARCHITECTURE.md</p> <pre><code>graph TB\n subgraph \"Browser\"\n UI[JavaScript View<br/>overview.js]\n API[API Module<br/>api.js]\n end\n\n subgraph \"LuCI Framework\"\n RPC[RPC Layer<br/>L.rpc]\n UHTTPD[uhttpd<br/>Web Server]\n end\n\n subgraph \"Backend\"\n RPCD[RPCD Daemon]\n SCRIPT[RPCD Script<br/>luci.module-name]\n UBUS[ubus]\n end\n\n subgraph \"System\"\n UCI[UCI Config]\n SYS[System Services]\n end\n\n UI -->|API calls| API\n API -->|RPC declare| RPC\n RPC -->|HTTP/JSON| UHTTPD\n UHTTPD -->|Call method| RPCD\n RPCD -->|Execute| SCRIPT\n SCRIPT -->|ubus call| UBUS\n UBUS -->|Read/Write| UCI\n UBUS -->|Control| SYS\n\n style UI fill:#6366f1,color:#fff\n style API fill:#8b5cf6,color:#fff\n style SCRIPT fill:#22c55e,color:#fff</code></pre>"},{"location":"todo-analyse/#42-deployment-workflow-diagram","title":"4.2. Deployment Workflow Diagram","text":"<p>Location: DEVELOPMENT-GUIDELINES.md \u00a79</p> <pre><code>flowchart TD\n START([Start Deployment]) --> CHECK1{Disk Space<br/>< 90%?}\n CHECK1 -->|No| CLEAN[Clean Temp Files]\n CLEAN --> CHECK1\n CHECK1 -->|Yes| COPY[Copy Files to Router]\n\n COPY --> FIX[Fix Permissions<br/>755 RPCD / 644 CSS-JS]\n FIX --> CACHE[Clear LuCI Cache]\n CACHE --> RESTART[Restart Services<br/>rpcd + uhttpd]\n\n RESTART --> VERIFY{Verify}\n VERIFY -->|ubus list| CHECK2{Object Found?}\n CHECK2 -->|No| DEBUG1[Debug RPCD<br/>Check naming]\n DEBUG1 --> FIX\n\n CHECK2 -->|Yes| CHECK3{Files Accessible?}\n CHECK3 -->|403 Error| DEBUG2[Fix Permissions<br/>chmod 644]\n DEBUG2 --> FIX\n\n CHECK3 -->|Yes| CHECK4{UI Loads?}\n CHECK4 -->|404 Error| DEBUG3[Fix Menu Path]\n DEBUG3 --> COPY\n\n CHECK4 -->|Yes| SUCCESS([\u2705 Success])\n\n style START fill:#6366f1,color:#fff\n style SUCCESS fill:#22c55e,color:#fff\n style DEBUG1 fill:#ef4444,color:#fff\n style DEBUG2 fill:#ef4444,color:#fff\n style DEBUG3 fill:#ef4444,color:#fff</code></pre>"},{"location":"todo-analyse/#43-component-hierarchy-diagram","title":"4.3. Component Hierarchy Diagram","text":"<p>Location: DEVELOPMENT-GUIDELINES.md \u00a71 (Design System)</p> <pre><code>graph TB\n PAGE[Page Container] --> HEADER[sh-page-header]\n PAGE --> CONTENT[sh-content]\n\n HEADER --> TITLE[sh-page-title<br/>+ gradient]\n HEADER --> SUBTITLE[sh-page-subtitle]\n HEADER --> STATS[sh-stats-grid]\n\n STATS --> BADGE1[sh-stat-badge]\n STATS --> BADGE2[sh-stat-badge]\n\n BADGE1 --> VALUE[sh-stat-value<br/>monospace]\n BADGE1 --> LABEL[sh-stat-label<br/>uppercase]\n\n CONTENT --> CARD1[sh-card]\n CONTENT --> CARD2[sh-card]\n\n CARD1 --> CARD_HEADER[sh-card-header]\n CARD1 --> CARD_BODY[sh-card-body]\n\n CARD_HEADER --> CARD_TITLE[sh-card-title]\n CARD_TITLE --> ICON[sh-card-title-icon]\n\n style PAGE fill:#0a0a0f,color:#fafafa,stroke:#6366f1\n style HEADER fill:#12121a,color:#fafafa,stroke:#6366f1\n style CARD1 fill:#12121a,color:#fafafa,stroke:#22c55e</code></pre> <p>Acceptance Criteria: - \u2705 3+ Mermaid diagrams added - \u2705 Diagrams render correctly on GitHub - \u2705 Diagrams included in relevant doc sections - \u2705 Alt text provided for accessibility</p>"},{"location":"todo-analyse/#5-create-missing-documentation-guides","title":"5. Create Missing Documentation Guides","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 6-8 hours</p> <p>Problem: - Testing practices not documented - Security best practices missing - Performance optimization not covered</p>"},{"location":"todo-analyse/#51-create-testingmd","title":"5.1. Create TESTING.md","text":"<p>Status: \u2b1c Not Started Estimated Time: 2-3 hours</p> <p>Outline: <pre><code># SecuBox Testing Guide\n\n## 1. Testing Philosophy\n- Unit tests for RPCD scripts\n- Integration tests for API modules\n- E2E tests for UI workflows\n- Manual testing checklist\n\n## 2. RPCD Script Testing\n- Test JSON output validity\n- Test error handling\n- Test edge cases\n- Mock ubus calls\n\n## 3. JavaScript Testing\n- Test API modules\n- Test view rendering\n- Test event handlers\n- Browser console checks\n\n## 4. Integration Testing\n- Test RPCD \u2194 JavaScript flow\n- Test UCI config read/write\n- Test service restarts\n- Test permission scenarios\n\n## 5. UI Testing\n- Manual testing checklist\n- Browser compatibility\n- Responsive design verification\n- Dark/Light mode verification\n\n## 6. Automated Testing\n- GitHub Actions integration\n- Pre-commit hooks\n- CI/CD test workflows\n- Test coverage reporting\n\n## 7. Testing Tools\n- shellcheck for RPCD\n- jsonlint for JSON\n- Browser DevTools\n- curl for API testing\n</code></pre></p> <p>Action Items: - [ ] Write TESTING.md (follow outline above) - [ ] Add test examples for RPCD scripts - [ ] Add test examples for JavaScript - [ ] Document testing workflow - [ ] Add to DOCUMENTATION-INDEX.md</p>"},{"location":"todo-analyse/#52-create-securitymd","title":"5.2. Create SECURITY.md","text":"<p>Status: \u2b1c Not Started Estimated Time: 2-3 hours</p> <p>Outline: <pre><code># SecuBox Security Guide\n\n## 1. Security Principles\n- Least privilege\n- Input validation\n- Output sanitization\n- Secure defaults\n\n## 2. RPCD Security\n- Input validation in shell scripts\n- Command injection prevention\n- JSON injection prevention\n- File permission security (755 vs 644)\n\n## 3. ACL Security\n- Minimal permissions\n- Read vs Write separation\n- User group management\n- Permission auditing\n\n## 4. JavaScript Security\n- XSS prevention\n- CSRF protection\n- Input sanitization\n- Safe DOM manipulation\n\n## 5. Common Vulnerabilities\n- Command injection (shell scripts)\n- Path traversal\n- Unsafe eval()\n- Hardcoded credentials\n\n## 6. Security Checklist\n- Pre-deployment security review\n- ACL validation\n- Permission audit\n- Credential management\n\n## 7. Incident Response\n- Security issue reporting\n- Patch procedures\n- Rollback procedures\n</code></pre></p> <p>Action Items: - [ ] Write SECURITY.md (follow outline above) - [ ] Add security examples (good vs bad) - [ ] Document security review process - [ ] Add to DOCUMENTATION-INDEX.md</p>"},{"location":"todo-analyse/#53-create-performancemd","title":"5.3. Create PERFORMANCE.md","text":"<p>Status: \u2b1c Not Started Estimated Time: 2 hours</p> <p>Outline: <pre><code># SecuBox Performance Guide\n\n## 1. Performance Goals\n- Page load < 2s\n- API response < 500ms\n- Smooth animations (60fps)\n- Minimal memory footprint\n\n## 2. RPCD Optimization\n- Efficient shell scripting\n- Caching strategies\n- Avoid expensive operations\n- Optimize JSON generation\n\n## 3. JavaScript Optimization\n- Minimize DOM manipulation\n- Debounce/throttle events\n- Efficient polling\n- Code splitting\n\n## 4. CSS Optimization\n- Minimize repaints\n- Use CSS variables\n- Optimize animations\n- Reduce specificity\n\n## 5. Network Optimization\n- Minimize API calls\n- Batch requests\n- Cache static assets\n- Compress responses\n\n## 6. Profiling & Monitoring\n- Browser DevTools profiling\n- Network tab analysis\n- Memory profiling\n- Performance metrics\n\n## 7. Common Performance Issues\n- Excessive polling\n- Memory leaks\n- Inefficient selectors\n- Large payloads\n</code></pre></p> <p>Action Items: - [ ] Write PERFORMANCE.md (follow outline above) - [ ] Add performance benchmarks - [ ] Document profiling tools - [ ] Add to DOCUMENTATION-INDEX.md</p> <p>Acceptance Criteria: - \u2705 TESTING.md created and complete - \u2705 SECURITY.md created and complete - \u2705 PERFORMANCE.md created and complete - \u2705 All added to DOCUMENTATION-INDEX.md - \u2705 Cross-references added to existing docs</p>"},{"location":"todo-analyse/#6-consolidate-validation-documentation","title":"6. Consolidate Validation Documentation","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 2 hours</p> <p>Problem: - Validation content duplicated across multiple docs - VALIDATION-GUIDE.md (495 lines) overlaps with DEVELOPMENT-GUIDELINES \u00a78 - PERMISSIONS-GUIDE.md (229 lines) overlaps with DEVELOPMENT-GUIDELINES \u00a78.2</p> <p>Strategy: Single Source + Quick References</p>"},{"location":"todo-analyse/#61-update-development-guidelinesmd","title":"6.1. Update DEVELOPMENT-GUIDELINES.md","text":"<p>Action Items: - [ ] Expand \u00a78 \"Validation Checklist\" with content from VALIDATION-GUIDE.md - [ ] Ensure all 7 validation checks documented - [ ] Add validation script usage examples - [ ] Mark as \"Complete Reference\"</p>"},{"location":"todo-analyse/#62-convert-validation-guidemd-to-quick-reference","title":"6.2. Convert VALIDATION-GUIDE.md to Quick Reference","text":"<p>Action Items: - [ ] Reduce to ~200 lines (quick command reference) - [ ] Add prominent link to DEVELOPMENT-GUIDELINES \u00a78 - [ ] Keep command examples only - [ ] Remove detailed explanations (link to main guide)</p> <p>New Structure: <pre><code># Validation Quick Reference\n\n> **\ud83d\udcda Complete Guide:** [DEVELOPMENT-GUIDELINES.md \u00a78](development-guidelines.md#validation-checklist)\n\n## Quick Commands\n\n### Run All Checks\n```bash\n./secubox-tools/validate-modules.sh\n</code></pre></p>"},{"location":"todo-analyse/#individual-checks","title":"Individual Checks","text":"<pre><code># Check 1: RPCD naming\n# Check 2: Menu paths\n# ...\n</code></pre>"},{"location":"todo-analyse/#see-also","title":"See Also","text":"<ul> <li>Detailed validation guide: [DEVELOPMENT-GUIDELINES.md \u00a78]</li> <li>Pre-commit checklist: [DEVELOPMENT-GUIDELINES.md \u00a78.1]</li> <li>Post-deploy checklist: [DEVELOPMENT-GUIDELINES.md \u00a78.3] <pre><code>#### 6.3. Convert PERMISSIONS-GUIDE.md to Quick Reference\n\n**Action Items:**\n- [ ] Reduce to ~150 lines\n- [ ] Add prominent link to DEVELOPMENT-GUIDELINES \u00a79.2\n- [ ] Keep quick fixes only\n- [ ] Emphasize automated fix script\n\n**New Structure:**\n```markdown\n# Permissions Quick Reference\n\n> **\ud83d\udcda Complete Guide:** [DEVELOPMENT-GUIDELINES.md \u00a79](development-guidelines.md#deployment-procedures)\n\n## Quick Fix (Automated)\n\n```bash\n# Local (before commit)\n./secubox-tools/fix-permissions.sh --local\n\n# Remote (after deploy)\n./secubox-tools/fix-permissions.sh --remote\n</code></pre></li> </ul>"},{"location":"todo-analyse/#manual-fix","title":"Manual Fix","text":"<pre><code># RPCD = 755\nchmod 755 /usr/libexec/rpcd/luci.*\n\n# CSS/JS = 644\nchmod 644 /www/luci-static/resources/**/*.{css,js}\n</code></pre>"},{"location":"todo-analyse/#see-also_1","title":"See Also","text":"<ul> <li>Complete deployment guide: [DEVELOPMENT-GUIDELINES.md \u00a79]</li> <li>Permission validation: [DEVELOPMENT-GUIDELINES.md \u00a78.2] <pre><code>**Acceptance Criteria:**\n- \u2705 DEVELOPMENT-GUIDELINES \u00a78 is complete reference\n- \u2705 VALIDATION-GUIDE reduced to ~200 lines\n- \u2705 PERMISSIONS-GUIDE reduced to ~150 lines\n- \u2705 All quick references link to main guide\n- \u2705 No content loss (moved to main guide)\n\n---\n\n### 7. Add UI Component Examples\n\n**Status:** \u2b1c Not Started\n**Assignee:** _TBD_\n**Estimated Time:** 3 hours\n\n**Problem:**\n- Design system documented but no visual examples\n- Hard to understand component appearance from CSS alone\n- No screenshot reference for contributors\n\n**Action Items:**\n- [ ] Create `docs/images/` directory\n- [ ] Take screenshots of key UI components\n- [ ] Add to DEVELOPMENT-GUIDELINES \u00a71\n- [ ] Create visual component library page\n\n**Screenshots Needed:**\n\n- `docs/images/components/page-header-light.png`\n- `docs/images/components/page-header-dark.png`\n- `docs/images/components/stat-badges.png`\n- `docs/images/components/card-gradient-border.png`\n- `docs/images/components/card-success-border.png`\n- `docs/images/components/buttons-all-variants.png`\n- `docs/images/components/filter-tabs-active.png`\n- `docs/images/components/nav-tabs-sticky.png`\n- `docs/images/components/grid-layouts.png`\n- `docs/images/components/dark-light-comparison.png`\n\n**Add to DEVELOPMENT-GUIDELINES.md:** Once screenshots exist, embed them directly in \u00a71 (component patterns) with short captions describing required styles and grid behavior.\n\n**Optional: Interactive Component Library**\n\nCreate `docs/components/index.html` - Interactive showcase:\n- Live examples of all components\n- Code snippets\n- Dark/Light mode toggle\n- Responsive preview\n\n**Acceptance Criteria:**\n- \u2705 10+ component screenshots added\n- \u2705 Images added to relevant doc sections\n- \u2705 Dark and light mode examples\n- \u2705 Responsive examples included\n\n---\n\n<div id=\"long-term-actions-this-quarter\"></div>\n## Long-term Actions (This Quarter) {#long-term-actions-this-quarter}\n\n### Priority: \ud83d\udfe2 LOW | Effort: \u26a1\u26a1\u26a1 High | Impact: \ud83c\udfaf Medium\n\n### 8. Documentation Automation\n\n**Status:** \u2b1c Not Started\n**Assignee:** _TBD_\n**Estimated Time:** 8-12 hours\n\n#### 8.1. Version Synchronization Script\n\n**Problem:** Manual version updates error-prone\n\n**Create:** `scripts/sync-doc-versions.sh`\n\n```bash\n#!/bin/bash\n# Sync documentation versions\n\nVERSION=${1:-\"1.0.0\"}\nDATE=$(date +%Y-%m-%d)\n\necho \"Syncing docs to version $VERSION (date: $DATE)\"\n\n# Update all markdown files\nfind . -maxdepth 1 -name \"*.md\" -type f | while read -r file; do\n if grep -q \"^**Version:**\" \"$file\"; then\n sed -i \"s/^\\*\\*Version:\\*\\*.*/\\*\\*Version:\\*\\* $VERSION/\" \"$file\"\n sed -i \"s/^\\*\\*Last Updated:\\*\\*.*/\\*\\*Last Updated:\\*\\* $DATE/\" \"$file\"\n echo \"\u2713 Updated $file\"\n fi\ndone\n</code></pre></li> </ul> <p>Action Items: - [ ] Create version sync script - [ ] Add to pre-release checklist - [ ] Document in DOCUMENTATION-INDEX.md</p>"},{"location":"todo-analyse/#82-stale-content-detection","title":"8.2. Stale Content Detection","text":"<p>Problem: No way to detect outdated documentation</p> <p>Create: <code>scripts/check-stale-docs.sh</code></p> <pre><code>#!/bin/bash\n# Check for stale documentation\n\nWARN_DAYS=90 # Warn if not updated in 90 days\nERROR_DAYS=180 # Error if not updated in 180 days\n\nfind . -maxdepth 1 -name \"*.md\" -type f | while read -r file; do\n # Extract date from file\n date_str=$(grep \"Last Updated:\" \"$file\" | grep -oP '\\d{4}-\\d{2}-\\d{2}')\n\n if [ -n \"$date_str\" ]; then\n # Calculate age\n age_days=$(( ($(date +%s) - $(date -d \"$date_str\" +%s)) / 86400 ))\n\n if [ $age_days -gt $ERROR_DAYS ]; then\n echo \"\u274c $file is $age_days days old (>$ERROR_DAYS)\"\n elif [ $age_days -gt $WARN_DAYS ]; then\n echo \"\u26a0\ufe0f $file is $age_days days old (>$WARN_DAYS)\"\n fi\n fi\ndone\n</code></pre> <p>Action Items: - [ ] Create stale content detector - [ ] Add to CI/CD pipeline - [ ] Set up monthly review reminders</p>"},{"location":"todo-analyse/#83-auto-generate-api-documentation","title":"8.3. Auto-generate API Documentation","text":"<p>Problem: API documentation manually maintained</p> <p>Tools to Evaluate: - JSDoc for JavaScript - ShellDoc for shell scripts - Custom script for RPCD methods</p> <p>Action Items: - [ ] Evaluate documentation generators - [ ] Create API doc generation script - [ ] Integrate into build process - [ ] Add to CI/CD</p> <p>Acceptance Criteria: - \u2705 Version sync script working - \u2705 Stale content detection in CI - \u2705 API docs auto-generated from code</p>"},{"location":"todo-analyse/#9-interactive-documentation","title":"9. Interactive Documentation","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 12-16 hours</p>"},{"location":"todo-analyse/#91-searchable-documentation-site","title":"9.1. Searchable Documentation Site","text":"<p>Options: - GitHub Pages with mkdocs - Docusaurus - VuePress - Custom static site</p> <p>Features: - Full-text search - Version selector - Dark/Light theme - Mobile-responsive - Table of contents sidebar</p> <p>Action Items: - [ ] Evaluate documentation frameworks - [ ] Choose platform (recommend: mkdocs-material) - [ ] Configure and deploy - [ ] Set up automatic deployment</p>"},{"location":"todo-analyse/#92-interactive-code-examples","title":"9.2. Interactive Code Examples","text":"<p>Features: - Live code editor (CodePen/JSFiddle embeds) - Component playground - RPCD JSON validator - CSS variable playground</p> <p>Action Items: - [ ] Create interactive examples for key components - [ ] Embed in documentation site - [ ] Add to CODE-TEMPLATES.md</p>"},{"location":"todo-analyse/#93-video-tutorials","title":"9.3. Video Tutorials","text":"<p>Topics: - Getting started (10 min) - Creating a new module (20 min) - Debugging common errors (15 min) - Deployment workflow (10 min)</p> <p>Action Items: - [ ] Script video content - [ ] Record screencasts - [ ] Host on YouTube - [ ] Embed in docs</p> <p>Acceptance Criteria: - \u2705 Documentation site deployed - \u2705 Full-text search working - \u2705 5+ interactive examples - \u2705 2+ video tutorials</p>"},{"location":"todo-analyse/#10-internationalization","title":"10. Internationalization","text":"<p>Status: \u2b1c Not Started Assignee: TBD Estimated Time: 20+ hours</p> <p>Problem: - Current docs mix French and English - DEVELOPMENT-GUIDELINES mostly French - Other docs mostly English</p> <p>Decision Required: - Option A: English-only (translate French sections) - Option B: Bilingual (full French + English versions) - Option C: As-is (mixed, target French developers)</p> <p>If Option A (English-only): - [ ] Translate DEVELOPMENT-GUIDELINES to English - [ ] Standardize all docs in English - [ ] Keep French in code comments only</p> <p>If Option B (Bilingual): <pre><code>docs/\n\u251c\u2500\u2500 en/\n\u2502 \u251c\u2500\u2500 DEVELOPMENT-GUIDELINES.md\n\u2502 \u251c\u2500\u2500 QUICK-START.md\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 fr/\n \u251c\u2500\u2500 DEVELOPMENT-GUIDELINES.md\n \u251c\u2500\u2500 QUICK-START.md\n \u2514\u2500\u2500 ...\n</code></pre></p> <p>Action Items: - [ ] Decide on i18n strategy - [ ] Document decision in DOCUMENTATION-INDEX.md - [ ] Implement chosen strategy - [ ] Set up translation maintenance process</p> <p>Acceptance Criteria: - \u2705 Language strategy documented - \u2705 Consistent language use across docs - \u2705 Navigation supports chosen approach</p>"},{"location":"todo-analyse/#optional-enhancements","title":"Optional Enhancements","text":""},{"location":"todo-analyse/#priority-nice-to-have-effort-variable-impact-low-medium","title":"Priority: \ud83d\udd35 NICE-TO-HAVE | Effort: Variable | Impact: \ud83c\udfaf Low-Medium","text":""},{"location":"todo-analyse/#11-documentation-quality-metrics","title":"11. Documentation Quality Metrics","text":"<p>Tools: - Vale (prose linter) - markdownlint (markdown linter) - write-good (writing style checker)</p> <p>Action Items: - [ ] Set up automated linting - [ ] Configure style guide (Microsoft, Google, or custom) - [ ] Add to CI/CD - [ ] Fix existing issues</p>"},{"location":"todo-analyse/#12-contributor-onboarding-guide","title":"12. Contributor Onboarding Guide","text":"<p>Create: <code>CONTRIBUTING.md</code></p> <p>Sections: - How to contribute - Code of conduct - Documentation standards - PR process - Review guidelines</p>"},{"location":"todo-analyse/#13-faq-document","title":"13. FAQ Document","text":"<p>Create: <code>FAQ.md</code></p> <p>Sections: - Common questions from DEVELOPMENT-GUIDELINES \u00a77 - Troubleshooting quick links - Best practices summary</p>"},{"location":"todo-analyse/#14-changelog","title":"14. Changelog","text":"<p>Create: <code>CHANGELOG.md</code></p> <p>Track documentation changes: <pre><code># Changelog\n\n## [1.1.0] - 2025-XX-XX\n\n### Added\n- TESTING.md - Complete testing guide\n- SECURITY.md - Security best practices\n- Architecture diagrams\n\n### Changed\n- VALIDATION-GUIDE.md - Reduced to quick reference\n- DEVELOPMENT-GUIDELINES.md - Expanded validation section\n\n### Removed\n- COMPLETION_REPORT.md - Moved to docs/archive/\n</code></pre></p>"},{"location":"todo-analyse/#tracking-metrics","title":"Tracking & Metrics","text":""},{"location":"todo-analyse/#success-metrics","title":"Success Metrics","text":"Metric Current Target Status Documentation Coverage 90% 95% \ud83d\udfe1 Average Document Age <30 days <60 days \ud83d\udfe2 Cross-Reference Density Low High \ud83d\udd34 Visual Documentation 0% 30% \ud83d\udd34 User Satisfaction N/A 4.5/5 -"},{"location":"todo-analyse/#progress-tracking","title":"Progress Tracking","text":"<p>Immediate (Week 1): - [ ] Task 1: Version standardization (30 min) - [ ] Task 2: Cross-references (1 hr) - [ ] Task 3: Archive historical docs (15 min)</p> <p>Progress: 0/3 (0%)</p> <p>Short-term (Month 1): - [ ] Task 4: Architecture diagrams (4 hrs) - [ ] Task 5.1: TESTING.md (3 hrs) - [ ] Task 5.2: SECURITY.md (3 hrs) - [ ] Task 5.3: PERFORMANCE.md (2 hrs) - [ ] Task 6: Consolidate validation docs (2 hrs) - [ ] Task 7: UI component examples (3 hrs)</p> <p>Progress: 0/6 (0%)</p> <p>Long-term (Quarter 1): - [ ] Task 8: Documentation automation (12 hrs) - [ ] Task 9: Interactive documentation (16 hrs) - [ ] Task 10: Internationalization (20 hrs)</p> <p>Progress: 0/3 (0%)</p>"},{"location":"todo-analyse/#review-schedule","title":"Review Schedule","text":"Review Type Frequency Next Review Quick Review Weekly TBD Deep Review Monthly TBD Audit Quarterly TBD"},{"location":"todo-analyse/#notes-decisions","title":"Notes & Decisions","text":""},{"location":"todo-analyse/#decision-log","title":"Decision Log","text":"Date Decision Rationale Status 2025-12-28 Keep current redundancy model Standalone usability important \u2705 Accepted TBD I18n strategy (EN/FR/Mixed) Pending stakeholder input \u23f3 Pending TBD Documentation site platform Pending evaluation \u23f3 Pending"},{"location":"todo-analyse/#risks-concerns","title":"Risks & Concerns","text":"<ol> <li>Maintenance Burden: More docs = more maintenance</li> <li> <p>Mitigation: Automation (Task 8)</p> </li> <li> <p>Translation Cost: Bilingual docs double the effort</p> </li> <li> <p>Mitigation: Choose English-only or use translation tools</p> </li> <li> <p>Diagram Maintenance: Diagrams can become outdated</p> </li> <li>Mitigation: Generate from code where possible</li> </ol>"},{"location":"todo-analyse/#dependencies","title":"Dependencies","text":"<ul> <li>External: GitHub Pages (if chosen for doc site)</li> <li>Internal: secubox-tools scripts must be stable</li> <li>Human: Technical writer for video tutorials (optional)</li> </ul>"},{"location":"todo-analyse/#quick-start-guide-using-this-todo","title":"Quick Start Guide (Using This TODO)","text":""},{"location":"todo-analyse/#for-immediate-action","title":"For Immediate Action:","text":"<pre><code># 1. Start with immediate tasks\n# Complete tasks 1-3 this week (2 hours total)\n\n# 2. Review and prioritize short-term\n# Schedule 4-7 over next month\n\n# 3. Plan long-term initiatives\n# Quarterly planning for 8-10\n</code></pre>"},{"location":"todo-analyse/#for-project-management","title":"For Project Management:","text":"<ul> <li>Copy tasks to GitHub Issues/Projects</li> <li>Assign owners</li> <li>Set deadlines</li> <li>Track in Kanban board</li> </ul>"},{"location":"todo-analyse/#for-progress-updates","title":"For Progress Updates:","text":"<p>Update this file weekly: - Check off completed items: <code>- [x]</code> - Update progress percentages - Add notes to decision log</p> <p>Last Updated: 2025-12-28 Next Review: TBD Owner: TBD Status: \ud83d\udccb Active Planning</p>"},{"location":"validation-guide/","title":"SecuBox Module Validation Guide","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p> <p>\ud83d\udcda Complete Reference: This is a detailed validation guide. For quick commands, see QUICK-START.md</p> <p>Related Documentation: - Complete guide: DEVELOPMENT-GUIDELINES.md \u00a78 - Pre-commit checklist: DEVELOPMENT-GUIDELINES.md \u00a78.1 - Post-deploy checklist: DEVELOPMENT-GUIDELINES.md \u00a78.3 - Permissions guide: PERMISSIONS-GUIDE.md - Automation briefing: CODEX.md</p>"},{"location":"validation-guide/#see-also","title":"See Also","text":"<ul> <li>Quick Commands: QUICK-START.md</li> <li>Permissions Reference: PERMISSIONS-GUIDE.md</li> <li>Automation Guardrails: CODEX.md</li> <li>Deployment Procedures: DEVELOPMENT-GUIDELINES.md \u00a79</li> </ul> <p>This guide explains the validation checks performed on SecuBox modules during generation and before git push.</p>"},{"location":"validation-guide/#overview","title":"Overview","text":"<p>SecuBox uses a multi-layered validation approach:</p> <ol> <li>Module Generation Validation - Validates newly created/modified modules</li> <li>Pre-Push Validation - Blocks git push if critical issues are found</li> <li>Runtime Validation - Continuous checks on deployed modules</li> </ol>"},{"location":"validation-guide/#validation-tools","title":"Validation Tools","text":""},{"location":"validation-guide/#1-validate-module-generationsh","title":"1. validate-module-generation.sh","text":"<p>Comprehensive validation for a single module during/after generation.</p> <p>Usage: <pre><code>./secubox-tools/validate-module-generation.sh luci-app-cdn-cache\n</code></pre></p> <p>Checks performed: - \u2705 Makefile completeness and correctness - \u2705 RPCD script naming convention (must use <code>luci.</code> prefix) - \u2705 RPCD script executable permissions - \u2705 RPCD script structure (list/call handlers) - \u2705 ACL file JSON validity - \u2705 ACL permissions cover RPCD methods - \u2705 Menu file JSON validity - \u2705 Menu paths match view file locations - \u2705 JavaScript view files exist - \u2705 JavaScript strict mode usage - \u2705 RPC method calls match RPCD methods - \u2705 ubus object names match RPCD script names - \u2705 UCI config validity (if present) - \u2705 Security scan (hardcoded credentials, dangerous commands) - \u2705 Documentation presence</p> <p>Exit codes: - <code>0</code> - All checks passed - <code>1</code> - Critical errors found (module should not be deployed)</p>"},{"location":"validation-guide/#2-pre-push-validationsh","title":"2. pre-push-validation.sh","text":"<p>Validates all modules before allowing git push.</p> <p>Usage: <pre><code># Automatic (via git hook):\ngit push # validation runs automatically\n\n# Manual:\n./secubox-tools/pre-push-validation.sh\n</code></pre></p> <p>Checks performed: - \u2705 Git staged changes check - \u2705 RPCD naming conventions across all modules - \u2705 Menu path validation across all modules - \u2705 JSON syntax validation - \u2705 RPCD executable permissions - \u2705 ACL method coverage - \u2705 Makefile validation - \u2705 Security scans - \u2705 Full module validation on modified modules</p> <p>Exit codes: - <code>0</code> - Push allowed - <code>1</code> - Push blocked (critical errors)</p>"},{"location":"validation-guide/#3-validate-modulessh","title":"3. validate-modules.sh","text":"<p>Fast validation of all modules (existing tool).</p> <p>Usage: <pre><code>./secubox-tools/validate-modules.sh\n</code></pre></p> <p>See <code>secubox-tools/README.md</code> for details.</p>"},{"location":"validation-guide/#installing-git-hooks","title":"Installing Git Hooks","text":"<p>To enable automatic validation before git push:</p> <pre><code>./secubox-tools/install-git-hooks.sh\n</code></pre> <p>This creates a symbolic link from <code>.git/hooks/pre-push</code> to <code>secubox-tools/pre-push-validation.sh</code>.</p>"},{"location":"validation-guide/#critical-naming-conventions","title":"Critical Naming Conventions","text":""},{"location":"validation-guide/#1-rpcd-script-must-match-ubus-object","title":"1. RPCD Script MUST Match ubus Object","text":"<p>Rule: The RPCD script filename MUST exactly match the ubus object name declared in JavaScript.</p> <p>Why: LuCI's RPC system looks for RPCD scripts by their filename. If the name doesn't match, you get: - <code>RPC call failed with error -32000: Object not found</code> - <code>Command failed: Method not found</code></p> <p>Example:</p> <pre><code>// JavaScript (htdocs/luci-static/resources/view/cdn-cache/overview.js)\nvar callStatus = rpc.declare({\n object: 'luci.cdn-cache', // \u2190 This must match RPCD filename\n method: 'status'\n});\n</code></pre> <pre><code># RPCD script filename MUST be:\nroot/usr/libexec/rpcd/luci.cdn-cache # \u2190 Exactly 'luci.cdn-cache'\n</code></pre> <p>Common mistakes: - \u274c <code>root/usr/libexec/rpcd/cdn-cache</code> (missing <code>luci.</code> prefix) - \u274c <code>root/usr/libexec/rpcd/luci-cdn-cache</code> (using dash instead of dot) - \u274c <code>root/usr/libexec/rpcd/cdn_cache</code> (using underscore)</p> <p>Validation: <pre><code># Check naming:\n./secubox-tools/validate-module-generation.sh luci-app-cdn-cache\n\n# Look for:\n# \u2713 RPCD script follows naming convention (luci.* prefix)\n# \u2713 CRITICAL: RPCD script name matches ACL ubus object\n</code></pre></p>"},{"location":"validation-guide/#2-menu-paths-must-match-view-file-locations","title":"2. Menu Paths MUST Match View File Locations","text":"<p>Rule: Menu JSON <code>path</code> entries MUST correspond to actual view file paths.</p> <p>Why: LuCI loads views based on the path in the menu. Wrong path = HTTP 404.</p> <p>Example:</p> <pre><code>// Menu (root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json)\n{\n \"action\": {\n \"type\": \"view\",\n \"path\": \"netifyd-dashboard/overview\" // \u2190 Must match file location\n }\n}\n</code></pre> <pre><code># View file MUST exist at:\nhtdocs/luci-static/resources/view/netifyd-dashboard/overview.js\n# \u2191 Same path as menu \u2191\n</code></pre> <p>Common mistakes: - \u274c Menu: <code>\"path\": \"netifyd/overview\"</code> but file at <code>view/netifyd-dashboard/overview.js</code> - \u274c Menu: <code>\"path\": \"overview\"</code> but file at <code>view/netifyd-dashboard/overview.js</code></p> <p>Validation: <pre><code># Check paths:\n./secubox-tools/validate-module-generation.sh luci-app-netifyd-dashboard\n\n# Look for:\n# \u2713 Menu path 'netifyd-dashboard/overview' \u2192 view file EXISTS\n</code></pre></p>"},{"location":"validation-guide/#3-all-ubus-objects-must-use-luci-prefix","title":"3. All ubus Objects MUST Use <code>luci.</code> Prefix","text":"<p>Rule: Every ubus object declaration must start with <code>luci.</code></p> <p>Why: Consistent naming convention for LuCI applications. ACL system expects it.</p> <p>Example:</p> <pre><code>// \u2705 Correct:\nobject: 'luci.cdn-cache'\nobject: 'luci.system-hub'\nobject: 'luci.wireguard-dashboard'\n\n// \u274c Wrong:\nobject: 'cdn-cache' // Missing luci. prefix\nobject: 'systemhub' // Missing luci. prefix\n</code></pre> <p>Validation: <pre><code># Check convention:\n./secubox-tools/validate-modules.sh\n\n# Look for:\n# \u2713 ubus object 'luci.cdn-cache' follows naming convention\n</code></pre></p>"},{"location":"validation-guide/#module-generation-checklist","title":"Module Generation Checklist","text":"<p>Use this checklist when generating a new module:</p>"},{"location":"validation-guide/#phase-1-initial-generation","title":"Phase 1: Initial Generation","text":"<ul> <li> Create module directory: <code>luci-app-<module-name>/</code></li> <li> Generate Makefile with all required fields</li> <li> Create RPCD script at <code>root/usr/libexec/rpcd/luci.<module-name></code></li> <li> Make RPCD script executable: <code>chmod +x</code></li> <li> Add shebang to RPCD: <code>#!/bin/sh</code></li> <li> Implement RPCD methods (list, call, status, etc.)</li> <li> Create ACL file with read/write permissions</li> <li> Create menu JSON with correct paths</li> <li> Create view JavaScript files</li> <li> Add <code>'use strict';</code> to all JS files</li> </ul>"},{"location":"validation-guide/#phase-2-validation","title":"Phase 2: Validation","text":"<ul> <li> <p> Run module generation validation: <pre><code>./secubox-tools/validate-module-generation.sh luci-app-<module-name>\n</code></pre></p> </li> <li> <p> Fix all ERRORS (critical)</p> </li> <li> Review all WARNINGS (recommended)</li> </ul>"},{"location":"validation-guide/#phase-3-integration-validation","title":"Phase 3: Integration Validation","text":"<ul> <li> <p> Verify RPCD script name matches ubus object: <pre><code>grep -r \"object:\" luci-app-<module-name>/htdocs --include=\"*.js\"\nls -la luci-app-<module-name>/root/usr/libexec/rpcd/\n# Names must match exactly\n</code></pre></p> </li> <li> <p> Verify menu paths match view files: <pre><code>grep '\"path\":' luci-app-<module-name>/root/usr/share/luci/menu.d/*.json\nls -R luci-app-<module-name>/htdocs/luci-static/resources/view/\n# Paths must align\n</code></pre></p> </li> <li> <p> Verify ACL permissions cover all RPCD methods: <pre><code>grep 'case \"$2\"' luci-app-<module-name>/root/usr/libexec/rpcd/*\ngrep -A 20 '\"ubus\":' luci-app-<module-name>/root/usr/share/rpcd/acl.d/*.json\n# All methods should be in ACL\n</code></pre></p> </li> </ul>"},{"location":"validation-guide/#phase-4-pre-commit","title":"Phase 4: Pre-Commit","text":"<ul> <li> <p> Run comprehensive validation: <pre><code>./secubox-tools/validate-modules.sh\n</code></pre></p> </li> <li> <p> Review security scan results</p> </li> <li> <p> Check JSON validity: <pre><code>find luci-app-<module-name> -name \"*.json\" -exec python3 -m json.tool {} \\; > /dev/null\n</code></pre></p> </li> <li> <p> Optional: Run shellcheck on RPCD: <pre><code>shellcheck luci-app-<module-name>/root/usr/libexec/rpcd/*\n</code></pre></p> </li> </ul>"},{"location":"validation-guide/#phase-5-git-commit","title":"Phase 5: Git Commit","text":"<ul> <li> <p> Stage changes: <pre><code>git add luci-app-<module-name>\n</code></pre></p> </li> <li> <p> Commit with descriptive message: <pre><code>git commit -m \"feat: implement <module-name> module\n\n- Add RPCD backend with methods: status, get_*, set_*\n- Create views for overview, settings, etc.\n- Configure ACL permissions\n- Add menu entries\n\n\ud83e\udd16 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>\"\n</code></pre></p> </li> <li> <p> Push (validation runs automatically): <pre><code>git push\n</code></pre></p> </li> </ul>"},{"location":"validation-guide/#common-validation-errors-and-fixes","title":"Common Validation Errors and Fixes","text":""},{"location":"validation-guide/#error-rpcd-script-name-doesnt-match-ubus-object","title":"Error: RPCD script name doesn't match ubus object","text":"<pre><code>\u2717 ERROR: luci-app-cdn-cache: RPCD script 'cdn-cache' does NOT match ubus object 'luci.cdn-cache'\n</code></pre> <p>Fix: <pre><code>cd luci-app-cdn-cache/root/usr/libexec/rpcd\nmv cdn-cache luci.cdn-cache\n</code></pre></p>"},{"location":"validation-guide/#error-menu-path-file-not-found","title":"Error: Menu path \u2192 file NOT FOUND","text":"<pre><code>\u2717 ERROR: luci-app-netifyd: Menu path 'netifyd/overview' \u2192 file NOT FOUND\nExpected: htdocs/luci-static/resources/view/netifyd/overview.js\n</code></pre> <p>Fix Option 1: Update menu path to match file: <pre><code># Edit root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json\n# Change: \"path\": \"netifyd/overview\"\n# To: \"path\": \"netifyd-dashboard/overview\"\n</code></pre></p> <p>Fix Option 2: Move view file to match menu: <pre><code>mv htdocs/luci-static/resources/view/netifyd-dashboard \\\n htdocs/luci-static/resources/view/netifyd\n</code></pre></p>"},{"location":"validation-guide/#error-rpcd-script-is-not-executable","title":"Error: RPCD script is NOT executable","text":"<pre><code>\u2717 ERROR: luci-app-cdn-cache: luci.cdn-cache is NOT executable\n</code></pre> <p>Fix: <pre><code>chmod +x luci-app-cdn-cache/root/usr/libexec/rpcd/luci.cdn-cache\n</code></pre></p>"},{"location":"validation-guide/#error-method-get_stats-from-rpcd-not-found-in-acl","title":"Error: Method 'get_stats' from RPCD not found in ACL","text":"<pre><code>\u26a0 WARNING: luci-app-cdn-cache: Method 'get_stats' from RPCD not in ACL\n</code></pre> <p>Fix: <pre><code># Edit root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json\n# Add 'get_stats' to the read.ubus array:\n{\n \"luci-app-cdn-cache\": {\n \"read\": {\n \"ubus\": {\n \"luci.cdn-cache\": [\"status\", \"get_config\", \"get_stats\"]\n \u2191 Add here\n }\n }\n }\n}\n</code></pre></p>"},{"location":"validation-guide/#error-invalid-json-syntax","title":"Error: Invalid JSON syntax","text":"<pre><code>\u2717 ERROR: luci-app-cdn-cache: acl.d JSON is INVALID - syntax error\n</code></pre> <p>Fix: <pre><code># Validate JSON:\npython3 -m json.tool root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json\n\n# Common issues:\n# - Missing comma between array elements\n# - Trailing comma after last element\n# - Unescaped quotes in strings\n</code></pre></p>"},{"location":"validation-guide/#bypassing-validation-not-recommended","title":"Bypassing Validation (NOT RECOMMENDED)","text":"<p>In rare cases, you may need to bypass validation:</p> <pre><code># Skip pre-push validation:\ngit push --no-verify\n\n# Skip module generation validation:\n# (can't bypass - it's informational only)\n</code></pre> <p>\u26a0\ufe0f WARNING: Bypassing validation can lead to broken modules in production!</p>"},{"location":"validation-guide/#integration-with-cicd","title":"Integration with CI/CD","text":""},{"location":"validation-guide/#github-actions","title":"GitHub Actions","text":"<p>Add validation to your workflow:</p> <pre><code>name: Validate Modules\n\non: [push, pull_request]\n\njobs:\n validate:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install dependencies\n run: |\n sudo apt-get update\n sudo apt-get install -y python3 shellcheck\n\n - name: Run module validation\n run: |\n chmod +x secubox-tools/validate-modules.sh\n ./secubox-tools/validate-modules.sh\n\n - name: Run pre-push validation\n run: |\n chmod +x secubox-tools/pre-push-validation.sh\n ./secubox-tools/pre-push-validation.sh\n</code></pre>"},{"location":"validation-guide/#best-practices","title":"Best Practices","text":"<ol> <li> <p>Always validate before committing <pre><code>./secubox-tools/validate-module-generation.sh luci-app-<module>\n</code></pre></p> </li> <li> <p>Install git hooks for automatic validation <pre><code>./secubox-tools/install-git-hooks.sh\n</code></pre></p> </li> <li> <p>Fix errors immediately - Don't accumulate validation debt</p> </li> <li> <p>Review warnings - They often indicate real issues</p> </li> <li> <p>Test on OpenWrt before marking complete: <pre><code>scp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/\nssh root@192.168.1.1\nopkg install /tmp/luci-app-*.ipk\n/etc/init.d/rpcd restart\n/etc/init.d/uhttpd restart\n</code></pre></p> </li> <li> <p>Document module-specific requirements in module README</p> </li> </ol>"},{"location":"validation-guide/#troubleshooting","title":"Troubleshooting","text":""},{"location":"validation-guide/#validation-script-fails-to-run","title":"Validation script fails to run","text":"<pre><code># Make sure scripts are executable:\nchmod +x secubox-tools/*.sh\n\n# Check dependencies:\nwhich python3 # For JSON validation\nwhich shellcheck # For shell script validation\n</code></pre>"},{"location":"validation-guide/#git-hook-not-running","title":"Git hook not running","text":"<pre><code># Check hook is installed:\nls -la .git/hooks/pre-push\n\n# Reinstall hooks:\n./secubox-tools/install-git-hooks.sh\n</code></pre>"},{"location":"validation-guide/#false-positives-in-validation","title":"False positives in validation","text":"<p>If validation incorrectly reports an error, please report it: - Create issue with full validation output - Include module name and specific check that failed - We'll update validation logic</p>"},{"location":"validation-guide/#additional-resources","title":"Additional Resources","text":"<ul> <li>CLAUDE.md - Main project documentation</li> <li>secubox-tools/README.md - Tools documentation</li> <li>Feature Regeneration Prompts - Module generation prompts</li> </ul>"},{"location":"validation-guide/#support","title":"Support","text":"<p>If you encounter validation issues:</p> <ol> <li>Check this guide for common errors</li> <li>Run validation with verbose output</li> <li>Review CLAUDE.md for naming conventions</li> <li>Create issue on GitHub with validation output</li> </ol>"},{"location":"archive/","title":"Documentation Archive","text":"<p>Historical and completed documentation.</p>"},{"location":"archive/#purpose","title":"Purpose","text":"<p>This archive contains documents that: - Represent completed project milestones - Describe implemented features - Document resolved issues</p>"},{"location":"archive/#archived-documents","title":"Archived Documents","text":"<ul> <li>Build Issues - Historical build troubleshooting (resolved)</li> <li>Completion Report - Project completion milestone</li> <li>Module Enable/Disable Design - Feature design (implemented)</li> </ul>"},{"location":"archive/#archive-policy","title":"Archive Policy","text":"<p>Documents are archived when: 1. \u2705 Feature/project is completed 2. \u2705 Information is outdated but historically valuable 3. \u2705 Content has been migrated to active documentation 4. \u2705 Document serves as historical reference only</p> <p>\u2190 Back to Home</p>"},{"location":"archive/build-issues/","title":"Build Issues & Solutions","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p>"},{"location":"archive/build-issues/#current-problem-no-ipk-generated-on-github-actions","title":"Current Problem: No IPK Generated on GitHub Actions","text":""},{"location":"archive/build-issues/#root-cause","title":"Root Cause","text":"<p>The OpenWrt SDK cannot compile LuCI core dependencies (<code>lucihttp</code>, <code>cgi-io</code>) because it lacks the necessary <code>ubus</code> development headers. When building SecuBox packages, the SDK tries to compile all dependencies from source, which fails with:</p> <pre><code>ERROR: package/feeds/luci/lucihttp failed to build.\nubus_include_dir-NOTFOUND\n</code></pre>"},{"location":"archive/build-issues/#why-this-works-locally","title":"Why This Works Locally","text":"<p>Locally, you likely have one of these setups: 1. Full OpenWrt build tree - Has all headers and can compile everything 2. ImageBuilder - Uses pre-compiled packages, doesn't compile from source 3. Pre-installed dependencies - lucihttp/cgi-io already exist</p>"},{"location":"archive/build-issues/#why-it-fails-on-github-actions","title":"Why It Fails on GitHub Actions","text":"<p>GitHub Actions uses the OpenWrt SDK which: - \u2705 Can compile packages with compiled code - \u274c Cannot compile certain LuCI core packages (missing headers) - \u274c Tries to rebuild all dependencies from source</p>"},{"location":"archive/build-issues/#solutions","title":"Solutions","text":""},{"location":"archive/build-issues/#option-1-use-openwrt-imagebuilder-recommended","title":"Option 1: Use OpenWrt ImageBuilder (Recommended)","text":"<p>Best for: Creating firmware images with SecuBox pre-installed</p> <p>ImageBuilder uses pre-compiled packages and doesn't require compilation:</p> <pre><code># New workflow using ImageBuilder\n- name: Download ImageBuilder\n run: |\n wget https://downloads.openwrt.org/releases/${VERSION}/targets/${TARGET}/${SUBTARGET}/openwrt-imagebuilder-*.tar.xz\n tar xf openwrt-imagebuilder-*.tar.xz\n\n- name: Add custom packages\n run: |\n mkdir -p imagebuilder/packages/custom\n cp *.ipk imagebuilder/packages/custom/\n\n- name: Build image\n run: |\n cd imagebuilder\n make image PACKAGES=\"luci luci-app-secubox luci-app-*-dashboard\"\n</code></pre> <p>Pros: - \u2705 No compilation issues - \u2705 Creates complete firmware images - \u2705 Fast builds (uses binaries)</p> <p>Cons: - \u274c Requires specifying target device - \u274c Not suitable for multi-architecture package builds</p>"},{"location":"archive/build-issues/#option-2-use-full-openwrt-build-system","title":"Option 2: Use Full OpenWrt Build System","text":"<p>Best for: Complete control, custom kernels, or when you need to modify core packages</p> <p>Clone and build complete OpenWrt:</p> <pre><code>- name: Clone OpenWrt\n run: |\n git clone https://github.com/openwrt/openwrt.git\n cd openwrt\n ./scripts/feeds update -a\n ./scripts/feeds install -a\n\n- name: Add SecuBox packages\n run: |\n cp -r ../luci-app-* openwrt/package/\n\n- name: Build\n run: |\n cd openwrt\n make defconfig\n make -j$(nproc)\n</code></pre> <p>Pros: - \u2705 Can compile everything - \u2705 Full control over build - \u2705 Can modify core packages</p> <p>Cons: - \u274c Very slow (1-2 hours per architecture) - \u274c Requires significant disk space (30-50GB) - \u274c Complex configuration</p>"},{"location":"archive/build-issues/#option-3-package-only-repository-alternative","title":"Option 3: Package-Only Repository (Alternative)","text":"<p>Best for: Distributing packages that users install on existing OpenWrt systems</p> <p>Create a custom package feed:</p> <pre><code># On your server/GitHub Pages\nmkdir -p packages/${ARCH}/secubox\ncp *.ipk packages/${ARCH}/secubox/\nscripts/ipkg-make-index packages/${ARCH}/secubox > Packages\ngzip -c Packages > Packages.gz\n</code></pre> <p>Users add to <code>/etc/opkg/customfeeds.conf</code>: <pre><code>src/gz secubox https://yourdomain.com/packages/${ARCH}/secubox\n</code></pre></p> <p>Pros: - \u2705 No build needed (distribute sources) - \u2705 Users compile locally or use binaries - \u2705 Easy updates</p> <p>Cons: - \u274c Users need to manually install - \u274c Doesn't provide firmware images</p>"},{"location":"archive/build-issues/#option-4-fix-sdk-build-current-attempt","title":"Option 4: Fix SDK Build (Current Attempt)","text":"<p>The current workflow attempts workarounds: 1. Download package indices 2. Configure SDK to prefer binaries (CONFIG_BUILDBOT=y) 3. Fallback to direct packaging if compile fails</p> <p>Status: Experimental, may not work reliably</p> <p>Pros: - \u2705 Keeps existing workflow structure - \u2705 Multi-architecture builds</p> <p>Cons: - \u274c Fragile, depends on SDK quirks - \u274c May break with OpenWrt updates - \u274c Not officially supported</p>"},{"location":"archive/build-issues/#recommended-approach","title":"Recommended Approach","text":""},{"location":"archive/build-issues/#for-package-distribution","title":"For Package Distribution","text":"<p>Use Option 3 (Package Repository) combined with Option 1 (ImageBuilder for sample firmwares):</p> <ol> <li>Distribute source packages via GitHub releases</li> <li>Provide pre-built .ipk for common architectures (x86-64, ARM)</li> <li>Create sample firmwares with ImageBuilder for popular devices</li> <li>Document installation for users who want to install on existing OpenWrt</li> </ol>"},{"location":"archive/build-issues/#implementation-steps","title":"Implementation Steps","text":"<ol> <li>Create package feed workflow (replaces current SDK build)</li> <li>Add ImageBuilder workflow for sample firmwares (ESPRESSObin, x86-64, etc.)</li> <li>Update README with installation instructions</li> <li>Tag releases with both source and binaries</li> </ol>"},{"location":"archive/build-issues/#next-steps","title":"Next Steps","text":"<p>To implement the recommended solution:</p> <pre><code># 1. Create new workflow for ImageBuilder\ncp .github/workflows/build-secubox-images.yml .github/workflows/build-imagebuilder.yml\n# Edit to use ImageBuilder instead of full build\n\n# 2. Update package build workflow to create feed instead of compiling\n# (Keep source distribution, skip compilation)\n\n# 3. Update documentation\n# Add INSTALL.md with instructions for different scenarios\n</code></pre>"},{"location":"archive/build-issues/#temporary-workaround","title":"Temporary Workaround","text":"<p>Until the proper solution is implemented, users can:</p> <ol> <li>Download source from GitHub</li> <li>Build locally using local-build.sh (requires SDK setup)</li> <li>Or use existing firmware builds (when available)</li> </ol>"},{"location":"archive/build-issues/#references","title":"References","text":"<ul> <li>OpenWrt SDK: https://openwrt.org/docs/guide-developer/toolchain/using_the_sdk</li> <li>OpenWrt ImageBuilder: https://openwrt.org/docs/guide-user/additional-software/imagebuilder</li> <li>Package Feeds: https://openwrt.org/docs/guide-developer/feeds</li> </ul>"},{"location":"archive/completion-report/","title":"Rapport de Compl\u00e9tion - SecuBox Components","text":"<p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Active</p> <p>Version: 1.0.0 Last Updated: 2025-12-28 Status: Archived Report Date: 2025-12-23</p>"},{"location":"archive/completion-report/#resume-executif","title":"R\u00e9sum\u00e9 Ex\u00e9cutif","text":"<p>Les 13 composants LuCI SecuBox ont \u00e9t\u00e9 compl\u00e9t\u00e9s avec succ\u00e8s. Tous les fichiers essentiels sont maintenant pr\u00e9sents et fonctionnels.</p>"},{"location":"archive/completion-report/#statistiques-globales","title":"Statistiques Globales","text":"<ul> <li>Composants totaux: 13</li> <li>Composants complets: 13 (100%)</li> <li>Fichiers CSS cr\u00e9\u00e9s: 4</li> <li>Fichiers JavaScript: 79 total</li> <li>Backends RPCD: 14 total</li> </ul>"},{"location":"archive/completion-report/#composants-completes","title":"Composants Compl\u00e9t\u00e9s","text":""},{"location":"archive/completion-report/#1-luci-app-secubox-hub-central","title":"\u2705 1. luci-app-secubox (Hub Central)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backends: 2 (luci.secubox, secubox) - JavaScript: 4 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Dashboard centralis\u00e9 pour tous les modules SecuBox - Navigation unifi\u00e9e - Monitoring int\u00e9gr\u00e9</p>"},{"location":"archive/completion-report/#2-luci-app-system-hub-centre-de-controle-systeme","title":"\u2705 2. luci-app-system-hub (Centre de Contr\u00f4le Syst\u00e8me)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (753 lignes) - JavaScript: 8 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Gestion des composants (start/stop/restart) - Health monitoring avec score 0-100 - Assistance \u00e0 distance RustDesk - Collection de diagnostics - Logs unifi\u00e9s - T\u00e2ches planifi\u00e9es</p>"},{"location":"archive/completion-report/#3-luci-app-crowdsec-dashboard-securite-collaborative","title":"\u2705 3. luci-app-crowdsec-dashboard (S\u00e9curit\u00e9 Collaborative)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (267 lignes) - JavaScript: 5 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Monitoring des bans en temps r\u00e9el - Gestion des d\u00e9cisions IP - Dashboard de m\u00e9triques - Visualisation g\u00e9ographique des menaces - Th\u00e8me cybers\u00e9curit\u00e9 dark</p>"},{"location":"archive/completion-report/#4-luci-app-netdata-dashboard-monitoring-systeme","title":"\u2705 4. luci-app-netdata-dashboard (Monitoring Syst\u00e8me)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (463 lignes) - JavaScript: 5 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Monitoring CPU, m\u00e9moire, disque, r\u00e9seau - Capteurs de temp\u00e9rature - Moniteur de processus - Gauges et sparklines anim\u00e9s - Rafra\u00eechissement toutes les 2 secondes</p>"},{"location":"archive/completion-report/#5-luci-app-netifyd-dashboard-deep-packet-inspection","title":"\u2705 5. luci-app-netifyd-dashboard (Deep Packet Inspection)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (505 lignes) - JavaScript: 7 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - D\u00e9tection d'applications (Netflix, YouTube, Zoom) - Identification de protocoles (HTTP, HTTPS, DNS, QUIC) - Suivi des flux r\u00e9seau en direct - D\u00e9couverte automatique d'appareils - Cat\u00e9gorisation du trafic</p>"},{"location":"archive/completion-report/#6-luci-app-network-modes-configuration-reseau","title":"\u2705 6. luci-app-network-modes (Configuration R\u00e9seau)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (698 lignes) - JavaScript: 6 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Mode Sniffer: Bridge transparent pour analyse - Mode Access Point: WiFi AP avec 802.11r/k/v - Mode Relay: Extension r\u00e9seau avec WireGuard - Mode Router: Routeur complet avec proxy et HTTPS - Changement de mode en un clic avec backup</p>"},{"location":"archive/completion-report/#7-luci-app-wireguard-dashboard-gestion-vpn","title":"\u2705 7. luci-app-wireguard-dashboard (Gestion VPN)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (555 lignes) - JavaScript: 6 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Monitoring des tunnels - Gestion des peers (actif/idle/inactif) - Statistiques de trafic par peer - Visualisation de configuration - S\u00e9curis\u00e9 (cl\u00e9s priv\u00e9es jamais expos\u00e9es)</p>"},{"location":"archive/completion-report/#8-luci-app-client-guardian-controle-dacces-reseau","title":"\u2705 8. luci-app-client-guardian (Contr\u00f4le d'Acc\u00e8s R\u00e9seau)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (775 lignes) - JavaScript: 8 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - D\u00e9tection et monitoring en temps r\u00e9el des clients - Gestion des zones (LAN, IoT, Invit\u00e9s, Quarantaine) - Politique de quarantaine par d\u00e9faut - Portail captif moderne - Contr\u00f4le parental (limites de temps, filtrage de contenu) - Alertes SMS/Email</p>"},{"location":"archive/completion-report/#9-luci-app-auth-guardian-systeme-dauthentification","title":"\u2705 9. luci-app-auth-guardian (Syst\u00e8me d'Authentification)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (147 lignes) - JavaScript: 7 fichiers - CSS: 1 fichier \u2b50 NOUVEAU - Menu JSON \u2713 - ACL JSON \u2713</p> <p>CSS Cr\u00e9\u00e9: - <code>dashboard.css</code> (380+ lignes) - Th\u00e8me rouge s\u00e9curit\u00e9 (#ef4444) - Cartes de statistiques avec hover effects - Styles pour OAuth, vouchers, sessions - Animations pulse pour \u00e9tats actifs</p> <p>Fonctionnalit\u00e9s: - Portail captif personnalisable - Int\u00e9gration OAuth (Google, GitHub, Facebook, Twitter) - Syst\u00e8me de vouchers avec limites - Gestion de sessions s\u00e9curis\u00e9es - R\u00e8gles de bypass MAC/IP/Domain</p>"},{"location":"archive/completion-report/#10-luci-app-bandwidth-manager-qos-quotas","title":"\u2705 10. luci-app-bandwidth-manager (QoS & Quotas)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (192 lignes) - JavaScript: 7 fichiers - CSS: 1 fichier \u2b50 NOUVEAU - Menu JSON \u2713 - ACL JSON \u2713</p> <p>CSS Cr\u00e9\u00e9: - <code>dashboard.css</code> (600+ lignes) - Th\u00e8me violet gradient (#8b5cf6 \u2192 #6366f1) - Classes QoS avec barres de progression - Styles pour quotas avec \u00e9tats (normal/warning/exceeded) - D\u00e9tection de m\u00e9dias avec cartes de services - Timeline de trafic avec graphiques</p> <p>Fonctionnalit\u00e9s: - 8 classes de priorit\u00e9 QoS configurables - Quotas journaliers et mensuels - D\u00e9tection automatique de m\u00e9dias (VoIP, Gaming, Streaming) - Planification bas\u00e9e sur le temps - Statistiques par client</p>"},{"location":"archive/completion-report/#11-luci-app-media-flow-detection-de-trafic-media","title":"\u2705 11. luci-app-media-flow (D\u00e9tection de Trafic M\u00e9dia)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (125 lignes) - JavaScript: 5 fichiers - CSS: 1 fichier \u2b50 NOUVEAU - Menu JSON \u2713 - ACL JSON \u2713</p> <p>CSS Cr\u00e9\u00e9: - <code>dashboard.css</code> (680+ lignes) - Th\u00e8me rose-violet gradient (#ec4899 \u2192 #8b5cf6) - Cartes de services de streaming - D\u00e9tection de protocoles avec badges - Appels VoIP avec indicateur live pulsant - Quality of Experience meter avec scores - Timeline de trafic avec graphiques \u00e0 barres</p> <p>Fonctionnalit\u00e9s: - D\u00e9tection de services de streaming en temps r\u00e9el - Identification de protocoles (RTSP, HLS, DASH, RTP) - Monitoring VoIP/Vid\u00e9o calls - Suivi de bande passante par service - M\u00e9triques de qualit\u00e9 d'exp\u00e9rience</p> <p>Services Support\u00e9s: - Netflix, YouTube, Twitch, Disney+ - Spotify, Apple Music, Tidal - Zoom, Teams, Google Meet, WebEx</p>"},{"location":"archive/completion-report/#12-luci-app-cdn-cache-optimisation-de-bande-passante","title":"\u2705 12. luci-app-cdn-cache (Optimisation de Bande Passante)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (692 lignes) - JavaScript: 7 fichiers - CSS: 1 fichier (dashboard.css) - Menu JSON \u2713 - ACL JSON \u2713</p> <p>Fonctionnalit\u00e9s: - Cache intelligent du contenu fr\u00e9quemment acc\u00e9d\u00e9 - Statistiques de hit ratio et \u00e9conomies en temps r\u00e9el - Policies configurables par domaine/extension - Purge et pr\u00e9chargement automatiques - Graphiques statistiques et tendances</p> <p>Policies de Cache: - Windows Update, d\u00e9p\u00f4ts Linux - Contenu statique (JS, CSS, images) - TTL configurable par type</p>"},{"location":"archive/completion-report/#13-luci-app-vhost-manager-gestion-dhotes-virtuels","title":"\u2705 13. luci-app-vhost-manager (Gestion d'H\u00f4tes Virtuels)","text":"<p>Fichiers: - Makefile \u2713 - RPCD backend: 1 (145 lignes) - JavaScript: 5 fichiers - CSS: 1 fichier \u2b50 NOUVEAU - Menu JSON \u2713 - ACL JSON \u2713</p> <p>CSS Cr\u00e9\u00e9: - <code>dashboard.css</code> (700+ lignes) - Th\u00e8me cyan (#06b6d4) - Cartes de vhosts avec badges SSL - Redirections avec fl\u00e8ches anim\u00e9es - Templates de services avec hover effects - Preview de configuration Nginx/HAProxy - Setup Let's Encrypt ACME avec domaines v\u00e9rifi\u00e9s</p> <p>Fonctionnalit\u00e9s: - H\u00f4tes virtuels internes avec domaines personnalis\u00e9s - Redirection de services externes - SSL/TLS avec Let's Encrypt ou auto-sign\u00e9 - Configuration automatique de reverse proxy nginx</p> <p>Services Support\u00e9s: - Nextcloud, GitLab, Jellyfin - Home Assistant et plus</p>"},{"location":"archive/completion-report/#fichiers-css-crees","title":"Fichiers CSS Cr\u00e9\u00e9s","text":""},{"location":"archive/completion-report/#1-auth-guardiandashboardcss","title":"1. auth-guardian/dashboard.css","text":"<p>Lignes: 380+ Th\u00e8me: Rouge s\u00e9curit\u00e9 Caract\u00e9ristiques: - Variables CSS pour couleurs coh\u00e9rentes - Cartes de statistiques avec hover effects - Styles OAuth avec boutons color\u00e9s par provider - Syst\u00e8me de vouchers avec badges de statut - Table de sessions avec indicateurs actifs pulsants - R\u00e8gles de bypass avec badges typ\u00e9s - Formulaires et boutons d'action - Responsive design</p>"},{"location":"archive/completion-report/#2-bandwidth-managerdashboardcss","title":"2. bandwidth-manager/dashboard.css","text":"<p>Lignes: 600+ Th\u00e8me: Violet gradient Caract\u00e9ristiques: - Grid de statistiques avec cartes anim\u00e9es - 8 classes QoS avec barres de progression - Variations de couleurs par priorit\u00e9 - Syst\u00e8me de quotas avec \u00e9tats (normal/warning/exceeded) - D\u00e9tection de m\u00e9dias avec grille de services - Planifications temporelles avec badges de jours - Table de statistiques clients avec barres d'usage - Indicateur live en temps r\u00e9el</p>"},{"location":"archive/completion-report/#3-media-flowdashboardcss","title":"3. media-flow/dashboard.css","text":"<p>Lignes: 680+ Th\u00e8me: Rose-violet gradient Caract\u00e9ristiques: - Grille de services de streaming avec ic\u00f4nes - Filtres de cat\u00e9gories avec \u00e9tats actifs - D\u00e9tection de protocoles avec compteurs - Appels VoIP avec statut pulsant - Quality of Experience meter avec scores color\u00e9s - Timeline de trafic avec graphiques interactifs - \u00c9tats loading et empty avec animations - Design responsive complet</p>"},{"location":"archive/completion-report/#4-vhost-managerdashboardcss","title":"4. vhost-manager/dashboard.css","text":"<p>Lignes: 700+ Th\u00e8me: Cyan Caract\u00e9ristiques: - Liste de vhosts avec badges SSL - Statut online/offline avec dots anim\u00e9s - Redirections avec fl\u00e8ches et routes - Templates de services avec hover scale - Preview de configuration code (Nginx/HAProxy) - Setup ACME Let's Encrypt avec tags de domaines - Info boxes avec styles par type - \u00c9tats loading, empty et responsive</p>"},{"location":"archive/completion-report/#patterns-et-standards-css-utilises","title":"Patterns et Standards CSS Utilis\u00e9s","text":""},{"location":"archive/completion-report/#variables-css-root","title":"Variables CSS Root","text":"<p>Chaque dashboard d\u00e9finit ses propres variables pour: - Couleurs primaires et secondaires - Tons dark/darker/light - Couleurs de bordure - Couleurs de statut (success/warning/danger/info) - Gradients sp\u00e9cifiques</p>"},{"location":"archive/completion-report/#composants-communs","title":"Composants Communs","text":"<ul> <li>Containers: Background gradients, border-radius, padding, shadow</li> <li>Headers: Flexbox, border-bottom, titre avec emoji et gradient text</li> <li>Stats Grid: Auto-fit responsive grid, cards avec hover effects</li> <li>Buttons: Variantes primary/secondary/danger avec transitions</li> <li>Forms: Inputs, selects, textareas avec focus states</li> <li>Tables: Hover states, border-collapse, padding coh\u00e9rent</li> <li>Badges: Pills avec backgrounds transparents color\u00e9s</li> <li>Loading States: Animations avec emojis et keyframes</li> <li>Empty States: Centr\u00e9 avec emojis de grande taille</li> </ul>"},{"location":"archive/completion-report/#animations","title":"Animations","text":"<ul> <li><code>pulse</code>: Opacit\u00e9 clignotante pour indicateurs</li> <li><code>blink</code>: Clignotement pour dots live</li> <li><code>spin</code>/<code>rotate</code>: Rotation pour loading</li> <li><code>pulse-green</code>: Pulse avec box-shadow pour VoIP</li> <li>Hover transforms: <code>translateY(-2px)</code>, <code>scale(1.05)</code></li> </ul>"},{"location":"archive/completion-report/#responsive-design","title":"Responsive Design","text":"<ul> <li>Grid auto-fit avec minmax</li> <li>Media queries \u00e0 768px pour mobile</li> <li>Colonnes 1fr pour petits \u00e9crans</li> <li>Font sizes et paddings adapt\u00e9s</li> </ul>"},{"location":"archive/completion-report/#architecture-technique","title":"Architecture Technique","text":""},{"location":"archive/completion-report/#structure-standard-de-package","title":"Structure Standard de Package","text":"<pre><code>luci-app-<module>/\n\u251c\u2500\u2500 Makefile # D\u00e9finition package OpenWrt\n\u251c\u2500\u2500 README.md # Documentation module\n\u251c\u2500\u2500 htdocs/luci-static/resources/\n\u2502 \u251c\u2500\u2500 view/<module>/ # Vues JavaScript UI\n\u2502 \u2502 \u251c\u2500\u2500 overview.js # Dashboard principal\n\u2502 \u2502 \u2514\u2500\u2500 *.js # Vues additionnelles\n\u2502 \u2514\u2500\u2500 <module>/\n\u2502 \u251c\u2500\u2500 api.js # Client API RPC\n\u2502 \u2514\u2500\u2500 dashboard.css # Styles du module\n\u2514\u2500\u2500 root/\n \u251c\u2500\u2500 etc/config/<module> # Config UCI (optionnel)\n \u2514\u2500\u2500 usr/\n \u251c\u2500\u2500 libexec/rpcd/<module> # Backend RPCD\n \u2514\u2500\u2500 share/\n \u251c\u2500\u2500 luci/menu.d/ # D\u00e9finition menu JSON\n \u2502 \u2514\u2500\u2500 luci-app-<module>.json\n \u2514\u2500\u2500 rpcd/acl.d/ # Permissions ACL JSON\n \u2514\u2500\u2500 luci-app-<module>.json\n</code></pre>"},{"location":"archive/completion-report/#technologies-utilisees","title":"Technologies Utilis\u00e9es","text":"<ul> <li>Frontend: LuCI framework (JavaScript)</li> <li>Backend: Shell scripts (RPCD)</li> <li>Styling: CSS3 avec variables et animations</li> <li>Configuration: UCI (Unified Configuration Interface)</li> <li>API: ubus RPC calls</li> <li>Packaging: OpenWrt Makefile system</li> </ul>"},{"location":"archive/completion-report/#validation-et-tests","title":"Validation et Tests","text":""},{"location":"archive/completion-report/#checks-effectues","title":"Checks Effectu\u00e9s","text":"<p>\u2705 Pr\u00e9sence de tous les Makefiles \u2705 Backends RPCD existants et ex\u00e9cutables \u2705 Fichiers JavaScript pr\u00e9sents (79 total) \u2705 Fichiers CSS pr\u00e9sents (13 total, 4 nouveaux) \u2705 Fichiers menu.d JSON valides \u2705 Fichiers ACL JSON valides</p>"},{"location":"archive/completion-report/#prochaines-etapes-recommandees","title":"Prochaines \u00c9tapes Recommand\u00e9es","text":"<ol> <li>Build Test: Compiler chaque package avec OpenWrt SDK</li> <li>Lint Validation: <pre><code>shellcheck luci-app-*/root/usr/libexec/rpcd/*\njsonlint luci-app-*/root/usr/share/{luci/menu.d,rpcd/acl.d}/*.json\n</code></pre></li> <li>Installation Test: D\u00e9ployer sur un routeur OpenWrt de test</li> <li>Functional Test: V\u00e9rifier chaque fonctionnalit\u00e9 UI</li> <li>Integration Test: Tester l'interop\u00e9rabilit\u00e9 entre modules</li> <li>CI/CD: D\u00e9clencher le workflow GitHub Actions</li> </ol>"},{"location":"archive/completion-report/#outils-et-scripts","title":"Outils et Scripts","text":""},{"location":"archive/completion-report/#outils-de-reparation","title":"Outils de R\u00e9paration","text":"<ul> <li><code>secubox-tools/secubox-repair.sh</code>: Auto-fix des probl\u00e8mes Makefile et RPCD</li> <li><code>secubox-tools/secubox-debug.sh</code>: Validation et diagnostics</li> </ul>"},{"location":"archive/completion-report/#scripts-de-validation","title":"Scripts de Validation","text":"<pre><code># V\u00e9rifier tous les composants\nfor comp in luci-app-*; do\n echo \"Checking $comp...\"\n [ -f \"$comp/Makefile\" ] && echo \" \u2713 Makefile\"\n [ -d \"$comp/root/usr/libexec/rpcd\" ] && echo \" \u2713 RPCD\"\n [ -d \"$comp/htdocs\" ] && echo \" \u2713 Frontend\"\ndone\n</code></pre>"},{"location":"archive/completion-report/#licence","title":"Licence","text":"<p>Tous les modules SecuBox sont sous licence Apache-2.0 \u00a9 2025 CyberMind.fr</p>"},{"location":"archive/completion-report/#auteur","title":"Auteur","text":"<p>Gandalf - CyberMind.fr</p>"},{"location":"archive/completion-report/#conclusion","title":"Conclusion","text":"<p>\u2705 Mission accomplie! Les 13 composants LuCI SecuBox sont maintenant complets et pr\u00eats pour: - Build et packaging - Tests fonctionnels - D\u00e9ploiement sur OpenWrt - Int\u00e9gration dans SecuBox Suite</p> <p>Date de compl\u00e9tion: 23 d\u00e9cembre 2025 Status final: \ud83c\udf89 100% COMPLET</p> <p>Rapport g\u00e9n\u00e9r\u00e9 automatiquement par Claude Code</p>"},{"location":"archive/module-enable-disable-design/","title":"Module Enable/Disable Design Document","text":"<p>Version: 0.3.1 Date: 2025-12-27 Author: Claude Code + CyberMind</p>"},{"location":"archive/module-enable-disable-design/#objectif","title":"\ud83c\udfaf Objectif","text":"<p>Remplacer la logique start/stop des modules SecuBox par une logique enable/disable (activ\u00e9/d\u00e9sactiv\u00e9), car les modules sont des plugins install\u00e9s qu'on souhaite activer ou d\u00e9sactiver, plut\u00f4t que des services qu'on d\u00e9marre ou arr\u00eate ponctuellement.</p>"},{"location":"archive/module-enable-disable-design/#changements-conceptuels","title":"\ud83d\udccb Changements Conceptuels","text":""},{"location":"archive/module-enable-disable-design/#avant-v02x","title":"Avant (v0.2.x)","text":"<pre><code>Module install\u00e9 \u2192 peut \u00eatre \"Running\" ou \"Stopped\"\nActions: Start / Stop / Restart\n\u00c9tat affich\u00e9: \"Running\" (vert) ou \"Stopped\" (gris)\n</code></pre>"},{"location":"archive/module-enable-disable-design/#apres-v031","title":"Apr\u00e8s (v0.3.1+)","text":"<pre><code>Module install\u00e9 \u2192 peut \u00eatre \"Enabled\" ou \"Disabled\"\nActions: Enable / Disable\n\u00c9tat affich\u00e9: \"Activ\u00e9\" (vert) ou \"D\u00e9sactiv\u00e9\" (gris)\nInfo compl\u00e9mentaire: \"Service running\" (si enabled + running)\n</code></pre>"},{"location":"archive/module-enable-disable-design/#architecture-technique","title":"\ud83c\udfd7\ufe0f Architecture Technique","text":""},{"location":"archive/module-enable-disable-design/#1-configuration-uci","title":"1. Configuration UCI","text":"<p>Chaque module dans <code>/etc/config/secubox</code> aura un champ <code>enabled</code>:</p> <pre><code>config module 'crowdsec'\n option name 'CrowdSec Dashboard'\n option package 'luci-app-crowdsec-dashboard'\n option config 'crowdsec'\n option category 'security'\n option enabled '1' # NEW: 1 = activ\u00e9, 0 = d\u00e9sactiv\u00e9\n option icon '\ud83d\udee1\ufe0f'\n option color '#ef4444'\n</code></pre>"},{"location":"archive/module-enable-disable-design/#2-methodes-rpcd-lucisecubox","title":"2. M\u00e9thodes RPCD (<code>luci.secubox</code>)","text":""},{"location":"archive/module-enable-disable-design/#anciennes-methodes-deprecated","title":"Anciennes m\u00e9thodes (DEPRECATED)","text":"<ul> <li>\u274c <code>start_module(module_id)</code> \u2192 d\u00e9marre le service</li> <li>\u274c <code>stop_module(module_id)</code> \u2192 arr\u00eate le service</li> <li>\u274c <code>restart_module(module_id)</code> \u2192 red\u00e9marre le service</li> </ul>"},{"location":"archive/module-enable-disable-design/#nouvelles-methodes-v031","title":"Nouvelles m\u00e9thodes (v0.3.1+)","text":"<pre><code>// Active un module (config UCI + d\u00e9marrage service)\nenable_module(module_id)\n\u2192 uci set secubox.${module}.enabled='1'\n\u2192 uci commit secubox\n\u2192 /etc/init.d/${service} enable\n\u2192 /etc/init.d/${service} start\n\u2192 return { success: true, message: \"Module activ\u00e9\" }\n\n// D\u00e9sactive un module (config UCI + arr\u00eat service)\ndisable_module(module_id)\n\u2192 uci set secubox.${module}.enabled='0'\n\u2192 uci commit secubox\n\u2192 /etc/init.d/${service} disable\n\u2192 /etc/init.d/${service} stop\n\u2192 return { success: true, message: \"Module d\u00e9sactiv\u00e9\" }\n\n// V\u00e9rifie si un module est activ\u00e9\ncheck_module_enabled(module_id)\n\u2192 return uci get secubox.${module}.enabled == '1'\n\n// V\u00e9rifie si le service tourne (info compl\u00e9mentaire)\ncheck_service_running(module_id)\n\u2192 return pgrep -f ${service} > /dev/null\n</code></pre>"},{"location":"archive/module-enable-disable-design/#3-structure-de-donnees-retournee","title":"3. Structure de donn\u00e9es retourn\u00e9e","text":"<pre><code>{\n \"modules\": [\n {\n \"id\": \"crowdsec\",\n \"name\": \"CrowdSec Dashboard\",\n \"category\": \"security\",\n \"installed\": true,\n \"enabled\": true, // \u00c9tat principal (config UCI)\n \"running\": true, // \u00c9tat du service (info)\n \"status\": \"active\", // enabled + running = \"active\"\n \"icon\": \"\ud83d\udee1\ufe0f\",\n \"color\": \"#ef4444\"\n },\n {\n \"id\": \"netdata\",\n \"name\": \"Netdata Monitoring\",\n \"category\": \"monitoring\",\n \"installed\": true,\n \"enabled\": false, // Module d\u00e9sactiv\u00e9\n \"running\": false,\n \"status\": \"disabled\", // Status affich\u00e9\n \"icon\": \"\ud83d\udcca\",\n \"color\": \"#22c55e\"\n }\n ]\n}\n</code></pre>"},{"location":"archive/module-enable-disable-design/#4-etats-possibles","title":"4. \u00c9tats Possibles","text":"enabled running status Badge UI Description <code>true</code> <code>true</code> <code>active</code> \u2713 Activ\u00e9 Module activ\u00e9 et service tourne <code>true</code> <code>false</code> <code>error</code> \u26a0\ufe0f Erreur Module activ\u00e9 mais service arr\u00eat\u00e9 (probl\u00e8me) <code>false</code> <code>false</code> <code>disabled</code> \u25cb D\u00e9sactiv\u00e9 Module d\u00e9sactiv\u00e9 (\u00e9tat normal) <code>false</code> <code>true</code> <code>unknown</code> ? Inconnu \u00c9tat incoh\u00e9rent (rare)"},{"location":"archive/module-enable-disable-design/#interface-utilisateur","title":"\ud83c\udfa8 Interface Utilisateur","text":""},{"location":"archive/module-enable-disable-design/#dashboard-principal-secubox-hub","title":"Dashboard Principal (SecuBox Hub)","text":"<p>Avant: <pre><code>[CrowdSec Dashboard] \u25cf Running [Stop] [Restart]\n[Netdata Monitor] \u25cb Stopped [Start]\n</code></pre></p> <p>Apr\u00e8s: <pre><code>[CrowdSec Dashboard] \u2713 Activ\u00e9 [D\u00e9sactiver]\n[Netdata Monitor] \u25cb D\u00e9sactiv\u00e9 [Activer]\n</code></pre></p>"},{"location":"archive/module-enable-disable-design/#module-individual-card","title":"Module Individual Card","text":"<pre><code><div class=\"module-card enabled\">\n <div class=\"module-header\">\n <span class=\"module-icon\">\ud83d\udee1\ufe0f</span>\n <span class=\"module-name\">CrowdSec Dashboard</span>\n <span class=\"module-badge enabled\">\u2713 Activ\u00e9</span>\n </div>\n <div class=\"module-status\">\n <span class=\"status-dot running\"></span>\n <span>Service en cours d'ex\u00e9cution</span>\n </div>\n <div class=\"module-actions\">\n <button class=\"btn-disable\">D\u00e9sactiver</button>\n </div>\n</div>\n</code></pre>"},{"location":"archive/module-enable-disable-design/#classes-css","title":"Classes CSS","text":"<pre><code>/* Module states */\n.module-badge.enabled {\n background: linear-gradient(135deg, #22c55e, #16a34a);\n color: white;\n}\n\n.module-badge.disabled {\n background: var(--sh-bg-secondary);\n color: var(--sh-text-muted);\n}\n\n.module-badge.error {\n background: linear-gradient(135deg, #f59e0b, #d97706);\n color: white;\n}\n\n/* Status indicators */\n.status-dot.running {\n background: #22c55e;\n animation: pulse 2s infinite;\n}\n\n.status-dot.stopped {\n background: #94a3b8;\n}\n</code></pre>"},{"location":"archive/module-enable-disable-design/#api-javascript","title":"\ud83d\udcdd API JavaScript","text":""},{"location":"archive/module-enable-disable-design/#fichier-secuboxapijs","title":"Fichier: <code>secubox/api.js</code>","text":"<pre><code>// Anciennes m\u00e9thodes (DEPRECATED - \u00e0 supprimer)\nstartModule: callStartModule, // DEPRECATED\nstopModule: callStopModule, // DEPRECATED\nrestartModule: callRestartModule, // DEPRECATED\n\n// Nouvelles m\u00e9thodes (v0.3.1+)\nenableModule: callEnableModule, // NEW\ndisableModule: callDisableModule, // NEW\n\n// D\u00e9clarations RPC\nvar callEnableModule = rpc.declare({\n object: 'luci.secubox',\n method: 'enable_module',\n params: ['module_id'],\n expect: { success: false, message: '' }\n});\n\nvar callDisableModule = rpc.declare({\n object: 'luci.secubox',\n method: 'disable_module',\n params: ['module_id'],\n expect: { success: false, message: '' }\n});\n</code></pre>"},{"location":"archive/module-enable-disable-design/#migration-des-donnees","title":"\ud83d\udd04 Migration des Donn\u00e9es","text":""},{"location":"archive/module-enable-disable-design/#script-de-migration-a-executer-une-fois","title":"Script de migration (\u00e0 ex\u00e9cuter une fois)","text":"<pre><code>#!/bin/sh\n# migrate-to-enable-disable.sh\n\n. /lib/functions.sh\n\nmigrate_module() {\n local module=\"$1\"\n local running=$(pgrep -f \"$module\" > /dev/null && echo \"1\" || echo \"0\")\n\n # Si le service tourne actuellement, on l'active\n if [ \"$running\" = \"1\" ]; then\n uci set secubox.${module}.enabled='1'\n else\n # Sinon, on le d\u00e9sactive par d\u00e9faut\n uci set secubox.${module}.enabled='0'\n fi\n}\n\n# Migrer tous les modules\nconfig_load secubox\nconfig_foreach migrate_module module\n\nuci commit secubox\necho \"Migration completed\"\n</code></pre>"},{"location":"archive/module-enable-disable-design/#documentation-utilisateur","title":"\ud83d\udcda Documentation Utilisateur","text":""},{"location":"archive/module-enable-disable-design/#readmemd-a-ajouter","title":"README.md (\u00e0 ajouter)","text":"<pre><code>## Gestion des Modules\n\nLes modules SecuBox sont des plugins install\u00e9s qui peuvent \u00eatre **activ\u00e9s** ou **d\u00e9sactiv\u00e9s**.\n\n### Activer un module\n- Cliquez sur le bouton **\"Activer\"** sur la carte du module\n- Le module sera configur\u00e9 pour d\u00e9marrer automatiquement au boot\n- Le service associ\u00e9 d\u00e9marrera imm\u00e9diatement\n\n### D\u00e9sactiver un module\n- Cliquez sur le bouton **\"D\u00e9sactiver\"** sur la carte du module\n- Le module ne d\u00e9marrera plus automatiquement au boot\n- Le service associ\u00e9 s'arr\u00eatera imm\u00e9diatement\n\n### \u00c9tats des modules\n\n| Badge | Signification |\n|-------|---------------|\n| \u2713 Activ\u00e9 | Module activ\u00e9 et service en cours d'ex\u00e9cution |\n| \u26a0\ufe0f Erreur | Module activ\u00e9 mais service arr\u00eat\u00e9 (v\u00e9rifier les logs) |\n| \u25cb D\u00e9sactiv\u00e9 | Module d\u00e9sactiv\u00e9 (normal) |\n\n**Note:** Les modules restent install\u00e9s m\u00eame lorsqu'ils sont d\u00e9sactiv\u00e9s. Pour les supprimer compl\u00e8tement, utilisez le gestionnaire de paquets APK.\n</code></pre>"},{"location":"archive/module-enable-disable-design/#tests-a-effectuer","title":"\ud83e\uddea Tests \u00e0 Effectuer","text":""},{"location":"archive/module-enable-disable-design/#tests-unitaires-rpcd","title":"Tests Unitaires RPCD","text":"<pre><code># Test enable_module\nubus call luci.secubox enable_module '{\"module_id\":\"crowdsec\"}'\n# Expected: {\"success\":true,\"message\":\"Module activ\u00e9\"}\n\n# V\u00e9rifier config UCI\nuci get secubox.crowdsec.enabled\n# Expected: 1\n\n# V\u00e9rifier service\n/etc/init.d/crowdsec enabled && echo \"OK\" || echo \"FAIL\"\npgrep crowdsec && echo \"Running\" || echo \"Not running\"\n\n# Test disable_module\nubus call luci.secubox disable_module '{\"module_id\":\"crowdsec\"}'\n# Expected: {\"success\":true,\"message\":\"Module d\u00e9sactiv\u00e9\"}\n\n# V\u00e9rifier\nuci get secubox.crowdsec.enabled\n# Expected: 0\n</code></pre>"},{"location":"archive/module-enable-disable-design/#tests-interface","title":"Tests Interface","text":"<ol> <li>\u2705 Ouvrir le dashboard SecuBox</li> <li>\u2705 V\u00e9rifier que les modules affichent \"Activ\u00e9\" ou \"D\u00e9sactiv\u00e9\"</li> <li>\u2705 Cliquer sur \"D\u00e9sactiver\" \u2192 badge passe \u00e0 \"\u25cb D\u00e9sactiv\u00e9\"</li> <li>\u2705 Cliquer sur \"Activer\" \u2192 badge passe \u00e0 \"\u2713 Activ\u00e9\"</li> <li>\u2705 V\u00e9rifier que le service d\u00e9marre/s'arr\u00eate r\u00e9ellement</li> <li>\u2705 Rafra\u00eechir la page \u2192 \u00e9tat persiste (UCI)</li> </ol>"},{"location":"archive/module-enable-disable-design/#modules-affectes","title":"\ud83d\udce6 Modules Affect\u00e9s","text":""},{"location":"archive/module-enable-disable-design/#secubox-hub-luci-app-secubox","title":"SecuBox Hub (<code>luci-app-secubox</code>)","text":"<p>Fichiers \u00e0 modifier: - \u2705 <code>root/usr/libexec/rpcd/luci.secubox</code> - Backend RPCD - \u2705 <code>htdocs/luci-static/resources/secubox/api.js</code> - API JS - \u2705 <code>htdocs/luci-static/resources/view/secubox/dashboard.js</code> - Dashboard - \u2705 <code>htdocs/luci-static/resources/view/secubox/modules.js</code> - Module list - \u2705 <code>htdocs/luci-static/resources/secubox/dashboard.css</code> - Styles - \u2705 <code>root/usr/share/rpcd/acl.d/luci-app-secubox.json</code> - ACL permissions - \u2705 <code>README.md</code> - Documentation</p>"},{"location":"archive/module-enable-disable-design/#system-hub-luci-app-system-hub","title":"System Hub (<code>luci-app-system-hub</code>)","text":"<p>Fichiers \u00e0 modifier: - \u2705 <code>htdocs/luci-static/resources/view/system-hub/components.js</code> - Vue composants - \u2705 <code>htdocs/luci-static/resources/view/system-hub/services.js</code> - Vue services - \u2705 <code>README.md</code> - Documentation</p>"},{"location":"archive/module-enable-disable-design/#benefices","title":"\ud83c\udfaf B\u00e9n\u00e9fices","text":"<ol> <li>Clart\u00e9 conceptuelle: \"Activer/D\u00e9sactiver\" est plus clair que \"D\u00e9marrer/Arr\u00eater\" pour des plugins</li> <li>Persistance: L'\u00e9tat persiste apr\u00e8s red\u00e9marrage (UCI + init.d enable/disable)</li> <li>Coh\u00e9rence: Tous les modules suivent la m\u00eame logique</li> <li>Meilleure UX: L'utilisateur comprend qu'il active/d\u00e9sactive des fonctionnalit\u00e9s</li> <li>Alignement OpenWrt: Utilise les m\u00e9canismes natifs (<code>/etc/init.d/${service} enable/disable</code>)</li> </ol>"},{"location":"archive/module-enable-disable-design/#prochaines-etapes","title":"\ud83d\udd1c Prochaines \u00c9tapes","text":"<ul> <li> Cr\u00e9er ce document de design</li> <li> Impl\u00e9menter les modifications RPCD</li> <li> Mettre \u00e0 jour l'API JavaScript</li> <li> Mettre \u00e0 jour les interfaces UI</li> <li> Mettre \u00e0 jour les ACL permissions</li> <li> Cr\u00e9er script de migration UCI</li> <li> Mettre \u00e0 jour la documentation</li> <li> Tester sur router de test</li> <li> D\u00e9ployer en production</li> </ul> <p>Maintainer: CyberMind contact@cybermind.fr License: Apache-2.0</p>"}]} |