zitinexus-router-script/ORGANIZATION_TOOLS_README.md

ZitiNexus UI File Organization Tools

This directory contains tools to maintain proper file organization for the ZitiNexus Router Enrollment UI and prevent the issues that previously broke the system.

📋 Available Tools

1. Development Instructions

File: UI/DEVELOPMENT_INSTRUCTIONS.md

• Purpose: Comprehensive guidelines for proper file organization
• When to use: Before making any changes to the UI codebase
• Contains: Mandatory file structure rules, coding standards, templates, and best practices

2. Organization Audit Script

Files:

• check-organization.ps1 (PowerShell - Windows)
• check-organization.sh (Bash - Linux/macOS)

Purpose: Automatically check for file organization issues Usage:

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File check-organization.ps1

# Linux/macOS
chmod +x check-organization.sh
./check-organization.sh

What it checks:

• ✅ Duplicate PHP files outside proper directories
• ✅ Required directory structure
• ✅ Required files existence
• ✅ Misplaced files
• ✅ Debug/test files that should be removed
• ✅ File permissions (when run as admin/root)

3. Organization Cleanup Script

File: cleanup-organization.ps1 (PowerShell - Windows)

Purpose: Automatically fix common file organization issues Usage:

powershell -ExecutionPolicy Bypass -File cleanup-organization.ps1

What it fixes:

• 🔧 Removes duplicate PHP files
• 🔧 Removes test files directory
• 🔧 Removes debug files from production directories
• 🔧 Removes misplaced assets directories
• 🔧 Creates missing required directories
• 🔧 Sets proper file permissions (when run as administrator)

🚀 Quick Start Workflow

Before Making Changes

1. Read the guidelines:

   Open UI/DEVELOPMENT_INSTRUCTIONS.md
   

2. Check current organization:

   powershell -ExecutionPolicy Bypass -File check-organization.ps1
   

After Making Changes

1. Run audit to check for issues:

   powershell -ExecutionPolicy Bypass -File check-organization.ps1
   

2. If issues found, run cleanup:

   powershell -ExecutionPolicy Bypass -File cleanup-organization.ps1
   

3. Verify fixes:

   powershell -ExecutionPolicy Bypass -File check-organization.ps1
   

Before Committing Code

MANDATORY Pre-commit checklist:

• Run check-organization.ps1 - should show "EXCELLENT: File organization is perfect!"
• No duplicate PHP files exist
• All test files have been removed
• All debug files have been removed
• Files are in correct directories per the guidelines

📁 Correct File Structure

UI/
├── public/                     # ✅ PUBLIC FILES ONLY
│   ├── index.php              # ✅ Login page
│   ├── dashboard.php          # ✅ Dashboard page
│   └── assets/                # ✅ Static assets
│       ├── css/style.css
│       └── js/app.js
├── includes/                   # ✅ BACKEND LOGIC ONLY
│   ├── config.php
│   ├── auth.php
│   ├── api_client.php
│   └── enrollment.php
├── logs/                       # ✅ Application logs
├── README.md
├── INSTALLATION_GUIDE.md
└── DEVELOPMENT_INSTRUCTIONS.md

❌ What NOT to Do

NEVER create these files/directories:

• ❌ UI/index.php (use UI/public/index.php)
• ❌ UI/dashboard.php (use UI/public/dashboard.php)
• ❌ UI/testfiles/ (remove after testing)
• ❌ UI/assets/ (use UI/public/assets/)
• ❌ Any PHP file outside /public/ or /includes/

🔧 Troubleshooting

"File organization is perfect!" but UI doesn't work

• Check web server configuration
• Ensure document root points to /public/ directory
• Verify file permissions
• Check PHP error logs

Audit script shows errors after cleanup

• Review the specific errors shown
• Check if files were recreated
• Ensure you have proper permissions
• Refer to UI/DEVELOPMENT_INSTRUCTIONS.md for manual fixes

PowerShell execution policy errors

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

📚 Additional Resources

• Detailed Guidelines: UI/DEVELOPMENT_INSTRUCTIONS.md
• Installation Guide: UI/INSTALLATION_GUIDE.md
• Main Documentation: UI/README.md

🆘 Emergency Recovery

If the UI system breaks due to file organization issues:

1. Stop web server
2. Run cleanup script:

   powershell -ExecutionPolicy Bypass -File cleanup-organization.ps1
   

3. Verify with audit script:

   powershell -ExecutionPolicy Bypass -File check-organization.ps1
   

4. Restart web server
5. Test UI functionality

---

Remember: The previous system breakage was caused by violating file organization principles. These tools exist to prevent that from happening again. Use them regularly and follow the guidelines religiously.