# SecuBox Architecture Notes

**Version:** 1.0.0  
**Last Updated:** 2025-12-28  
**Status:** Active

These notes summarize the repository structure, conventions, and supporting tooling gathered from `README.md`, `DOCS/QUICK-START.md`, `DOCS/DEVELOPMENT-GUIDELINES.md`, `DOCS/CODEX.md`, `DOCS/DOCUMENTATION-INDEX.md`, the various module READMEs, and the `secubox-tools/` scripts. Use this as a rapid orientation before extending the platform.

---

## Repository Layout (high level)

- **LuCI modules (`luci-app-*`)** – Each app bundles a LuCI frontend (JS under `htdocs/luci-static`), RPCD backend (shell scripts in `root/usr/libexec/rpcd/`), UCI defaults (`root/etc/config/...`), ACL/menu descriptors, and module-specific README (see e.g. `luci-app-netdata-dashboard/README.md`). Naming conventions follow the “menu path = view path” and “RPC object name = file name” rules emphasized in `DOCS/QUICK-START.md`.
- **Themes (`luci-theme-secubox`)** – Provides the shared SecuBox design tokens (`sh-*`, `sb-*` classes, palette, typography). All new UI should import `secubox-theme/secubox-theme.css` and leverage the CSS variables described in `DOCS/DEVELOPMENT-GUIDELINES.md`.
- **Core orchestration apps**
  - `luci-app-secubox`: global hub UI.
  - `luci-app-system-hub`: system health/remote assistance.
  - `luci-app-network-modes`: prebuilt router/sniffer modes (bridges, AP, relay, etc.).
  - `luci-app-vhost-manager`: reverse-proxy/vhost configuration (existing baseline for future work).
- **Tooling (`secubox-tools/`)** – Bash/POSIX scripts for validation, building, deployment, permission repair, etc. The README documents workflows such as `validate-modules.sh`, `local-build.sh`, `fix-permissions.sh`, and `deploy-*.sh`. The newer `secubox-app` helper consumes manifests under `/usr/share/secubox/plugins/` to install and configure “apps”.
- **Automation & Docs**
  - `DOCS/` + `docs/`: mirrored, versioned documentation tree (design system, prompts, module templates, validation, permissions, etc.).
  - `EXAMPLES/` and `templates/`: snippets and scaffolding.
  - CI workflows live in `.github/workflows/` (referenced from README badges).
- **Profiles & App Manifests**
  - App manifests (`/usr/share/secubox/plugins/`) and profile presets (`/usr/share/secubox/profiles/`) feed both the SecuBox wizard UI and the `secubox-app` CLI for automated installs.

---

## Coding & Packaging Standards

Summarized from `DOCS/QUICK-START.md`, `DOCS/DEVELOPMENT-GUIDELINES.md`, and `DOCS/CODEX.md`:

1. **RPCD/ubus**
   - RPC script filename **must** equal the ubus object (e.g., `root/usr/libexec/rpcd/luci.netdata-dashboard` ⇒ `object: 'luci.netdata-dashboard'`).
   - RPC scripts are executable (755) while JS/CSS assets are 644.
   - ACL and menu JSON entries shipped under `root/usr/share/rpcd/acl.d/` and `root/usr/share/luci/menu.d/`.
2. **LuCI Views**
   - Menu `path` mirrors `htdocs/luci-static/resources/view/...` location.
   - Use the SecuBox design system (`sh-*`/`sb-*` classes, Inter + JetBrains Mono, gradients). Avoid inline styles; rely on variables defined in `system-hub/common.css` or `secubox-theme`.
3. **UCI-first configuration**
   - Every feature stores runtime state in `/etc/config/<module>`.
   - CLI/scripts mutate config via `uci set/commit` and services watch UCI for changes.
4. **Service supervision**
   - Prefer `procd` init scripts (`/etc/init.d/<service>`) for daemons; ensure restart semantics and `ENABLE` flags.
5. **Validation workflow**
   - Run `./secubox-tools/validate-modules.sh` before PRs/releases. It checks permissions, RPC naming, LuCI assets, etc.
   - Use `./secubox-tools/local-build.sh build <module>` for SDK builds; `fix-permissions.sh` to normalize deployments.

---

## Networking & Firewall Conventions

Derived from `luci-app-network-modes`, `luci-app-client-guardian`, and docs:

- Network modes (router/sniffer/AP) are implemented via UCI (`/etc/config/network`, `/etc/config/wireless`) with helper scripts ensuring safe defaults and backups before applying.
- Firewall zones follow OpenWrt defaults (lan/wan) with additional zones per feature (IoT, Guest, Quarantine). Changes should add backup/rollback paths and never remove LAN management access.
- Reverse proxy/vhost management currently relies on `luci-app-vhost-manager`; new work should extend its UCI schema rather than inventing a parallel config.

---

## Storage & Runtime Expectations

- Target platform: OpenWrt 24.10.x (and preview 25.12 RC) on ARM64 per `README.md`. Flash is limited; prefer `/srv` or external storage for large artifacts (Docker/LXC images).
- Overlay space must be <90% before deploying; quick-start docs include SSH check commands.
- `/tmp` is tmpfs; don’t store persistent state there. Use `/srv/<app>` (Zigbee2MQTT), `/var/lib/<app>`, or configurable data roots.

---

## secubox-tools Highlights

- `validate-modules.sh` – structural lint, permissions, ubus paths.
- `local-build.sh` – OpenWrt SDK automation for building/testing packages (supports multiple arches).
- `fix-permissions.sh`, `deploy-*.sh` – remote deployment helpers with backup/restore.
- These scripts are POSIX shell friendly and should be leveraged (or extended) for new installers/diagnostics.

---

## Existing Modules & Patterns

- **Monitoring dashboards** (Netdata, Netifyd, CrowdSec, WireGuard, Traffic Shaper, Bandwidth Manager) provide consistent patterns for:
  - RPC APIs returning JSON for LuCI views.
  - JS views using `view.extend`, `poll` auto-refresh, and stat cards built with design system classes.
- **Security & NAC modules** (Client Guardian, Auth Guardian) showcase how to integrate with firewall/zones, handle ACL, and present complex forms in LuCI.
- **Network orchestration** (Network Modes, System Hub) demonstrates multi-step wizards, health checks, and service controls.
- **Theme & Navigation** (luci-theme-secubox, luci-app-secubox) define tab components, cascade helpers, and global CSS/JS assets.

Use these modules as references when building new “apps” to ensure consistent UX, RPC layout, and packaging.

---

## Documentation Requirements

- Every new or edited `.md` must follow the metadata header and versioning rules defined in `DOCS/DOCUMENTATION-INDEX.md`.
- Cross-link relevant guides (Quick Start, Dev Guidelines, Codex) when introducing new features.
- For platform-level additions (App Store, Vhost manager, DMZ mode, etc.), update both `DOCS/` and `docs/` to keep mkdocs + markdown parity.

---

## Future Work Context

`TODO-ANALYSE.md` highlights ongoing documentation and automation initiatives:
- Standardize version headers across documentation.
- Add “See Also” cross-links.
- Maintain an archive folder for legacy docs.
- Build new testing/performance/security guides.

Keep these in mind when touching docs or adding new features so we converge toward the roadmap.

---

This document will evolve alongside the App Store, Docker/LXC frameworks, and new wizard/profile systems. Update it whenever repository architecture or workflows change significantly.
