secubox-openwrt

Documentation Improvement TODO

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

Generated: 2025-12-28 Based on: Documentation Analysis Report Overall Health: 8.5/10 (Excellent) Status: 📋 Planning Phase

Table of Contents

  1. Immediate Actions (This Week)
  2. Short-term Actions (This Month)
  3. Long-term Actions (This Quarter)
  4. Optional Enhancements
  5. Tracking & Metrics

Immediate Actions (This Week)

Priority: 🔴 HIGH | Effort: ⚡ Low | Impact: 🎯 High

1. Standardize Document Versions & Dates

Status: ⬜ Not Started Assignee: TBD Estimated Time: 30 minutes

Problem:

Action Items:

Files to Update:

Missing version headers:
- CLAUDE.md
- BUILD_ISSUES.md
- LUCI_DEVELOPMENT_REFERENCE.md
- MODULE-ENABLE-DISABLE-DESIGN.md

Inconsistent dates:
- DOCUMENTATION-INDEX.md: 2025-12-27
- DEVELOPMENT-GUIDELINES.md: 2025-12-26
- QUICK-START.md: 2025-12-26

Template:

# Document Title

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

Acceptance Criteria:

2. Add Cross-References Between Documents

Status: ⬜ Not Started Assignee: TBD Estimated Time: 1 hour

Problem:

Action Items:

Specific Cross-References to Add:

QUICK-START.md:

## See Also

- **Complete Guide:** [DEVELOPMENT-GUIDELINES.md](/secubox-openwrt/development-guidelines.html)
- **Architecture Details:** [CLAUDE.md](/secubox-openwrt/claude.html) §2-6
- **Code Examples:** [CODE-TEMPLATES.md](/secubox-openwrt/code-templates.html)
- **Module Specs:** [FEATURE-REGENERATION-PROMPTS.md](/secubox-openwrt/feature-regeneration-prompts.html)

PERMISSIONS-GUIDE.md:

> **📚 This is a quick reference guide.**
> For complete deployment procedures, see [DEVELOPMENT-GUIDELINES.md §9](/secubox-openwrt/development-guidelines.html#deployment-procedures)

VALIDATION-GUIDE.md:

> **🔗 Related:**
> - Pre-commit checklist: [DEVELOPMENT-GUIDELINES.md §8.1](/secubox-openwrt/development-guidelines.html#pre-commit-checklist)
> - Deployment validation: [DEVELOPMENT-GUIDELINES.md §8.3](/secubox-openwrt/development-guidelines.html#post-deploy-checklist)

Acceptance Criteria:

3. Archive Historical Documents

Status: ⬜ Not Started Assignee: TBD Estimated Time: 15 minutes

Problem:

Action Items:

Documents to Archive:

mkdir -p docs/archive

# Historical/completed documents
mv COMPLETION_REPORT.md docs/archive/
mv MODULE-ENABLE-DISABLE-DESIGN.md docs/archive/

# Potentially merge/archive
# (Review before moving)
mv BUILD_ISSUES.md docs/archive/  # Merge into CLAUDE.md first?
mv LUCI_DEVELOPMENT_REFERENCE.md docs/archive/  # External reference

Create Archive README:

# docs/archive/README.md

# Documentation Archive

This directory contains historical and completed documentation.

## Contents

- **COMPLETION_REPORT.md** - Project completion report (2025-12-26)
- **MODULE-ENABLE-DISABLE-DESIGN.md** - Design document for enable/disable feature
- **BUILD_ISSUES.md** - Historical build issues (merged into CLAUDE.md)
- **LUCI_DEVELOPMENT_REFERENCE.md** - External LuCI development reference

## Active Documentation

For current documentation, see the root directory or [DOCUMENTATION-INDEX.md](../DOCUMENTATION-INDEX.md)

Acceptance Criteria:

Short-term Actions (This Month)

Priority: 🟡 MEDIUM | Effort: ⚡⚡ Medium | Impact: 🎯 High

4. Add Architecture Diagrams

Status: ⬜ Not Started Assignee: TBD Estimated Time: 3-4 hours

Problem:

Action Items:

Diagrams to Create:

4.1. System Architecture Diagram

Location: DEVELOPMENT-GUIDELINES.md §2 or new ARCHITECTURE.md

graph TB
    subgraph "Browser"
        UI[JavaScript View<br/>overview.js]
        API[API Module<br/>api.js]
    end

    subgraph "LuCI Framework"
        RPC[RPC Layer<br/>L.rpc]
        UHTTPD[uhttpd<br/>Web Server]
    end

    subgraph "Backend"
        RPCD[RPCD Daemon]
        SCRIPT[RPCD Script<br/>luci.module-name]
        UBUS[ubus]
    end

    subgraph "System"
        UCI[UCI Config]
        SYS[System Services]
    end

    UI -->|API calls| API
    API -->|RPC declare| RPC
    RPC -->|HTTP/JSON| UHTTPD
    UHTTPD -->|Call method| RPCD
    RPCD -->|Execute| SCRIPT
    SCRIPT -->|ubus call| UBUS
    UBUS -->|Read/Write| UCI
    UBUS -->|Control| SYS

    style UI fill:#6366f1,color:#fff
    style API fill:#8b5cf6,color:#fff
    style SCRIPT fill:#22c55e,color:#fff

4.2. Deployment Workflow Diagram

Location: DEVELOPMENT-GUIDELINES.md §9

flowchart TD
    START([Start Deployment]) --> CHECK1{Disk Space<br/>< 90%?}
    CHECK1 -->|No| CLEAN[Clean Temp Files]
    CLEAN --> CHECK1
    CHECK1 -->|Yes| COPY[Copy Files to Router]

    COPY --> FIX[Fix Permissions<br/>755 RPCD / 644 CSS-JS]
    FIX --> CACHE[Clear LuCI Cache]
    CACHE --> RESTART[Restart Services<br/>rpcd + uhttpd]

    RESTART --> VERIFY{Verify}
    VERIFY -->|ubus list| CHECK2{Object Found?}
    CHECK2 -->|No| DEBUG1[Debug RPCD<br/>Check naming]
    DEBUG1 --> FIX

    CHECK2 -->|Yes| CHECK3{Files Accessible?}
    CHECK3 -->|403 Error| DEBUG2[Fix Permissions<br/>chmod 644]
    DEBUG2 --> FIX

    CHECK3 -->|Yes| CHECK4{UI Loads?}
    CHECK4 -->|404 Error| DEBUG3[Fix Menu Path]
    DEBUG3 --> COPY

    CHECK4 -->|Yes| SUCCESS([✅ Success])

    style START fill:#6366f1,color:#fff
    style SUCCESS fill:#22c55e,color:#fff
    style DEBUG1 fill:#ef4444,color:#fff
    style DEBUG2 fill:#ef4444,color:#fff
    style DEBUG3 fill:#ef4444,color:#fff

4.3. Component Hierarchy Diagram

Location: DEVELOPMENT-GUIDELINES.md §1 (Design System)

graph TB
    PAGE[Page Container] --> HEADER[sh-page-header]
    PAGE --> CONTENT[sh-content]

    HEADER --> TITLE[sh-page-title<br/>+ gradient]
    HEADER --> SUBTITLE[sh-page-subtitle]
    HEADER --> STATS[sh-stats-grid]

    STATS --> BADGE1[sh-stat-badge]
    STATS --> BADGE2[sh-stat-badge]

    BADGE1 --> VALUE[sh-stat-value<br/>monospace]
    BADGE1 --> LABEL[sh-stat-label<br/>uppercase]

    CONTENT --> CARD1[sh-card]
    CONTENT --> CARD2[sh-card]

    CARD1 --> CARD_HEADER[sh-card-header]
    CARD1 --> CARD_BODY[sh-card-body]

    CARD_HEADER --> CARD_TITLE[sh-card-title]
    CARD_TITLE --> ICON[sh-card-title-icon]

    style PAGE fill:#0a0a0f,color:#fafafa,stroke:#6366f1
    style HEADER fill:#12121a,color:#fafafa,stroke:#6366f1
    style CARD1 fill:#12121a,color:#fafafa,stroke:#22c55e

Acceptance Criteria:

5. Create Missing Documentation Guides

Status: ⬜ Not Started Assignee: TBD Estimated Time: 6-8 hours

Problem:

5.1. Create TESTING.md

Status: ⬜ Not Started Estimated Time: 2-3 hours

Outline:

# SecuBox Testing Guide

## 1. Testing Philosophy
- Unit tests for RPCD scripts
- Integration tests for API modules
- E2E tests for UI workflows
- Manual testing checklist

## 2. RPCD Script Testing
- Test JSON output validity
- Test error handling
- Test edge cases
- Mock ubus calls

## 3. JavaScript Testing
- Test API modules
- Test view rendering
- Test event handlers
- Browser console checks

## 4. Integration Testing
- Test RPCD ↔ JavaScript flow
- Test UCI config read/write
- Test service restarts
- Test permission scenarios

## 5. UI Testing
- Manual testing checklist
- Browser compatibility
- Responsive design verification
- Dark/Light mode verification

## 6. Automated Testing
- GitHub Actions integration
- Pre-commit hooks
- CI/CD test workflows
- Test coverage reporting

## 7. Testing Tools
- shellcheck for RPCD
- jsonlint for JSON
- Browser DevTools
- curl for API testing

Action Items:

5.2. Create SECURITY.md

Status: ⬜ Not Started Estimated Time: 2-3 hours

Outline:

# SecuBox Security Guide

## 1. Security Principles
- Least privilege
- Input validation
- Output sanitization
- Secure defaults

## 2. RPCD Security
- Input validation in shell scripts
- Command injection prevention
- JSON injection prevention
- File permission security (755 vs 644)

## 3. ACL Security
- Minimal permissions
- Read vs Write separation
- User group management
- Permission auditing

## 4. JavaScript Security
- XSS prevention
- CSRF protection
- Input sanitization
- Safe DOM manipulation

## 5. Common Vulnerabilities
- Command injection (shell scripts)
- Path traversal
- Unsafe eval()
- Hardcoded credentials

## 6. Security Checklist
- Pre-deployment security review
- ACL validation
- Permission audit
- Credential management

## 7. Incident Response
- Security issue reporting
- Patch procedures
- Rollback procedures

Action Items:

5.3. Create PERFORMANCE.md

Status: ⬜ Not Started Estimated Time: 2 hours

Outline:

# SecuBox Performance Guide

## 1. Performance Goals
- Page load < 2s
- API response < 500ms
- Smooth animations (60fps)
- Minimal memory footprint

## 2. RPCD Optimization
- Efficient shell scripting
- Caching strategies
- Avoid expensive operations
- Optimize JSON generation

## 3. JavaScript Optimization
- Minimize DOM manipulation
- Debounce/throttle events
- Efficient polling
- Code splitting

## 4. CSS Optimization
- Minimize repaints
- Use CSS variables
- Optimize animations
- Reduce specificity

## 5. Network Optimization
- Minimize API calls
- Batch requests
- Cache static assets
- Compress responses

## 6. Profiling & Monitoring
- Browser DevTools profiling
- Network tab analysis
- Memory profiling
- Performance metrics

## 7. Common Performance Issues
- Excessive polling
- Memory leaks
- Inefficient selectors
- Large payloads

Action Items:

Acceptance Criteria:

6. Consolidate Validation Documentation

Status: ⬜ Not Started Assignee: TBD Estimated Time: 2 hours

Problem:

Strategy: Single Source + Quick References

6.1. Update DEVELOPMENT-GUIDELINES.md

Action Items:

6.2. Convert VALIDATION-GUIDE.md to Quick Reference

Action Items:

New Structure:

# Validation Quick Reference

> **📚 Complete Guide:** [DEVELOPMENT-GUIDELINES.md §8](/secubox-openwrt/development-guidelines.html#validation-checklist)

## Quick Commands

### Run All Checks
```bash
./secubox-tools/validate-modules.sh

Individual Checks

# Check 1: RPCD naming
# Check 2: Menu paths
# ...

See Also

6.3. Convert PERMISSIONS-GUIDE.md to Quick Reference

Action Items:

New Structure:

# Permissions Quick Reference

> **📚 Complete Guide:** [DEVELOPMENT-GUIDELINES.md §9](/secubox-openwrt/development-guidelines.html#deployment-procedures)

## Quick Fix (Automated)

```bash
# Local (before commit)
./secubox-tools/fix-permissions.sh --local

# Remote (after deploy)
./secubox-tools/fix-permissions.sh --remote

Manual Fix

# RPCD = 755
chmod 755 /usr/libexec/rpcd/luci.*

# CSS/JS = 644
chmod 644 /www/luci-static/resources/**/*.{css,js}

See Also

Acceptance Criteria:

7. Add UI Component Examples

Status: ⬜ Not Started Assignee: TBD Estimated Time: 3 hours

Problem:

Action Items:

Screenshots Needed:

Add to DEVELOPMENT-GUIDELINES.md: Once screenshots exist, embed them directly in §1 (component patterns) with short captions describing required styles and grid behavior.

Optional: Interactive Component Library

Create docs/components/index.html - Interactive showcase:

Acceptance Criteria:

Long-term Actions (This Quarter)

Priority: 🟢 LOW | Effort: ⚡⚡⚡ High | Impact: 🎯 Medium

8. Documentation Automation

Status: ⬜ Not Started Assignee: TBD Estimated Time: 8-12 hours

8.1. Version Synchronization Script

Problem: Manual version updates error-prone

Create: scripts/sync-doc-versions.sh

#!/bin/bash
# Sync documentation versions

VERSION=${1:-"1.0.0"}
DATE=$(date +%Y-%m-%d)

echo "Syncing docs to version $VERSION (date: $DATE)"

# Update all markdown files
find . -maxdepth 1 -name "*.md" -type f | while read -r file; do
    if grep -q "^**Version:**" "$file"; then
        sed -i "s/^\*\*Version:\*\*.*/\*\*Version:\*\* $VERSION/" "$file"
        sed -i "s/^\*\*Last Updated:\*\*.*/\*\*Last Updated:\*\* $DATE/" "$file"
        echo "✓ Updated $file"
    fi
done

Action Items:

8.2. Stale Content Detection

Problem: No way to detect outdated documentation

Create: scripts/check-stale-docs.sh

#!/bin/bash
# Check for stale documentation

WARN_DAYS=90  # Warn if not updated in 90 days
ERROR_DAYS=180  # Error if not updated in 180 days

find . -maxdepth 1 -name "*.md" -type f | while read -r file; do
    # Extract date from file
    date_str=$(grep "Last Updated:" "$file" | grep -oP '\d{4}-\d{2}-\d{2}')

    if [ -n "$date_str" ]; then
        # Calculate age
        age_days=$(( ($(date +%s) - $(date -d "$date_str" +%s)) / 86400 ))

        if [ $age_days -gt $ERROR_DAYS ]; then
            echo "❌ $file is $age_days days old (>$ERROR_DAYS)"
        elif [ $age_days -gt $WARN_DAYS ]; then
            echo "⚠️  $file is $age_days days old (>$WARN_DAYS)"
        fi
    fi
done

Action Items:

8.3. Auto-generate API Documentation

Problem: API documentation manually maintained

Tools to Evaluate:

Action Items:

Acceptance Criteria:

9. Interactive Documentation

Status: ⬜ Not Started Assignee: TBD Estimated Time: 12-16 hours

9.1. Searchable Documentation Site

Options:

Features:

Action Items:

9.2. Interactive Code Examples

Features:

Action Items:

9.3. Video Tutorials

Topics:

Action Items:

Acceptance Criteria:

10. Internationalization

Status: ⬜ Not Started Assignee: TBD Estimated Time: 20+ hours

Problem:

Decision Required:

If Option A (English-only):

If Option B (Bilingual):

docs/
├── en/
│   ├── DEVELOPMENT-GUIDELINES.md
│   ├── QUICK-START.md
│   └── ...
└── fr/
    ├── DEVELOPMENT-GUIDELINES.md
    ├── QUICK-START.md
    └── ...

Action Items:

Acceptance Criteria:

Optional Enhancements

Priority: 🔵 NICE-TO-HAVE | Effort: Variable | Impact: 🎯 Low-Medium

11. Documentation Quality Metrics

Tools:

Action Items:

12. Contributor Onboarding Guide

Create: CONTRIBUTING.md

Sections:

13. FAQ Document

Create: FAQ.md

Sections:

14. Changelog

Create: CHANGELOG.md

Track documentation changes:

# Changelog

## [1.1.0] - 2025-XX-XX

### Added
- TESTING.md - Complete testing guide
- SECURITY.md - Security best practices
- Architecture diagrams

### Changed
- VALIDATION-GUIDE.md - Reduced to quick reference
- DEVELOPMENT-GUIDELINES.md - Expanded validation section

### Removed
- COMPLETION_REPORT.md - Moved to docs/archive/

Tracking & Metrics

Success Metrics

Metric Current Target Status
Documentation Coverage 90% 95% 🟡
Average Document Age <30 days <60 days 🟢
Cross-Reference Density Low High 🔴
Visual Documentation 0% 30% 🔴
User Satisfaction N/A 4.5/5 -

Progress Tracking

Immediate (Week 1):

Progress: 0/3 (0%)

Short-term (Month 1):

Progress: 0/6 (0%)

Long-term (Quarter 1):

Progress: 0/3 (0%)

Review Schedule

Review Type Frequency Next Review
Quick Review Weekly TBD
Deep Review Monthly TBD
Audit Quarterly TBD

Notes & Decisions

Decision Log

Date Decision Rationale Status
2025-12-28 Keep current redundancy model Standalone usability important ✅ Accepted
TBD I18n strategy (EN/FR/Mixed) Pending stakeholder input ⏳ Pending
TBD Documentation site platform Pending evaluation ⏳ Pending

Risks & Concerns

  1. Maintenance Burden: More docs = more maintenance
    • Mitigation: Automation (Task 8)
  2. Translation Cost: Bilingual docs double the effort
    • Mitigation: Choose English-only or use translation tools
  3. Diagram Maintenance: Diagrams can become outdated
    • Mitigation: Generate from code where possible

Dependencies

Quick Start Guide (Using This TODO)

For Immediate Action:

# 1. Start with immediate tasks
# Complete tasks 1-3 this week (2 hours total)

# 2. Review and prioritize short-term
# Schedule 4-7 over next month

# 3. Plan long-term initiatives
# Quarterly planning for 8-10

For Project Management:

For Progress Updates:

Update this file weekly:

Last Updated: 2025-12-28 Next Review: TBD Owner: TBD Status: 📋 Active Planning