# ZitiNexus Router Enrollment UI - Development Instructions ## ⚠️ CRITICAL: File Organization Rules This document outlines **mandatory** development practices to prevent code duplication, maintain proper file organization, and ensure system stability. **Failure to follow these guidelines can break the entire UI system.** --- ## 1. STRICT FILE ORGANIZATION STRUCTURE ### 1.1 Directory Structure (MANDATORY) ``` UI/ ├── public/ # ✅ PUBLIC FILES ONLY - Web server document root │ ├── index.php # ✅ Login page (ONLY public-facing PHP file here) │ ├── dashboard.php # ✅ Dashboard page (ONLY public-facing PHP file here) │ └── assets/ # ✅ All static assets │ ├── css/ │ │ └── style.css │ ├── js/ │ │ └── app.js │ └── images/ ├── includes/ # ✅ BACKEND LOGIC ONLY - Never directly accessible │ ├── config.php # ✅ Configuration and utilities │ ├── auth.php # ✅ Authentication logic │ ├── api_client.php # ✅ API communication │ └── enrollment.php # ✅ Core enrollment logic ├── logs/ # ✅ Application logs ├── temp/ # ✅ Temporary files (if needed) ├── testfiles/ # ❌ REMOVE AFTER TESTING - Never in production ├── README.md # ✅ Documentation ├── INSTALLATION_GUIDE.md # ✅ Installation instructions ├── DEVELOPMENT_INSTRUCTIONS.md # ✅ This file └── install.sh # ✅ Installation script ``` ### 1.2 FORBIDDEN Practices ❌ **NEVER CREATE DUPLICATE PHP FILES** - ❌ `UI/index.php` (root level) - REMOVE THIS - ❌ `UI/dashboard.php` (root level) - REMOVE THIS - ❌ `UI/testfiles/dashboard.php` - REMOVE AFTER TESTING - ❌ Any PHP file outside `/public/` or `/includes/` directories ❌ **NEVER CREATE FILES IN WRONG LOCATIONS** - ❌ Public-facing files outside `/public/` - ❌ Backend logic files outside `/includes/` - ❌ Assets outside `/public/assets/` --- ## 2. FILE CREATION GUIDELINES ### 2.1 Public-Facing PHP Files **Location**: `/public/` directory ONLY **Rules**: - Must handle user interface and HTTP requests - Must include authentication checks - Must use relative paths for includes: `../includes/` - Must use relative paths for assets: `assets/` **Template for new public PHP files**: ```php <?php echo APP_NAME; ?> - [Page Title] ``` ### 2.2 Backend Logic Files **Location**: `/includes/` directory ONLY **Rules**: - Must contain only PHP logic (no HTML output) - Must be included by public files, never accessed directly - Must use proper error handling and logging **Template for new include files**: ```php Logo ``` --- ## 4. TESTING AND DEVELOPMENT WORKFLOW ### 4.1 Development Testing **For testing new features**: 1. ✅ Create test files in `/testfiles/` directory 2. ✅ Use clear naming: `test-[feature-name].php` 3. ✅ Document what you're testing 4. ✅ **ALWAYS CLEAN UP** after testing ### 4.2 Test File Cleanup (MANDATORY) **Before committing code**: ```bash # Remove all test files rm -rf UI/testfiles/ # Remove any duplicate files rm -f UI/index.php # Keep only public/index.php rm -f UI/dashboard.php # Keep only public/dashboard.php rm -f UI/debug-*.php # Remove debug files ``` ### 4.3 Pre-Commit Checklist - [ ] No duplicate PHP files exist - [ ] All public files are in `/public/` directory - [ ] All backend logic is in `/includes/` directory - [ ] All assets are in `/public/assets/` structure - [ ] Include paths are correct and relative - [ ] Asset paths are relative from public directory - [ ] Test files have been removed - [ ] No debug files remain --- ## 5. WEB SERVER CONFIGURATION ### 5.1 Document Root Configuration **MANDATORY**: Web server document root MUST point to `/public/` directory **Apache Virtual Host**: ```apache ServerName ziti-enrollment.local DocumentRoot /var/www/ziti-enrollment/public # ← CRITICAL: Points to public/ AllowOverride All Require all granted DirectoryIndex index.php ``` **Nginx Configuration**: ```nginx server { listen 80; server_name ziti-enrollment.local; root /var/www/ziti-enrollment/public; # ← CRITICAL: Points to public/ index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } } ``` ### 5.2 Security Benefits This structure provides: - ✅ Backend logic files are not directly accessible via web - ✅ Configuration files are protected - ✅ Only intended public files can be accessed - ✅ Proper separation of concerns --- ## 6. CODE QUALITY STANDARDS ### 6.1 PHP Coding Standards **File Headers**: ```php getMessage()); // Handle error appropriately } ``` **Input Sanitization**: ```php // ✅ ALWAYS sanitize user input $userInput = sanitizeInput($_POST['field'] ?? ''); ``` ### 6.2 Security Best Practices **Authentication Checks**: ```php // ✅ MANDATORY for all protected pages if (!isAuthenticated() || !isSessionValid()) { header('Location: index.php?error=session_expired'); exit; } ``` **CSRF Protection**: ```php // ✅ For all forms // ✅ For form processing if (!verifyCSRFToken($_POST['csrf_token'] ?? '')) { http_response_code(403); exit('CSRF token validation failed'); } ``` --- ## 7. DEPLOYMENT GUIDELINES ### 7.1 Production Deployment Checklist - [ ] Web server document root points to `/public/` - [ ] No test files exist in production - [ ] No duplicate files exist - [ ] File permissions are correct (755 for directories, 644 for files) - [ ] Log directories are writable (777 for `/logs/`) - [ ] Default passwords have been changed - [ ] Debug mode is disabled ### 7.2 File Permissions ```bash # Set proper permissions sudo chown -R www-data:www-data /var/www/ziti-enrollment sudo chmod -R 755 /var/www/ziti-enrollment sudo chmod -R 644 /var/www/ziti-enrollment/public/*.php sudo chmod -R 644 /var/www/ziti-enrollment/includes/*.php sudo chmod -R 777 /var/www/ziti-enrollment/logs ``` --- ## 8. TROUBLESHOOTING FILE ORGANIZATION ISSUES ### 8.1 Common Problems and Solutions **Problem**: "File not found" errors **Cause**: Incorrect include paths or files in wrong locations **Solution**: Verify file locations match this structure exactly **Problem**: Assets not loading (CSS/JS) **Cause**: Incorrect asset paths or document root misconfiguration **Solution**: Use relative paths and ensure document root points to `/public/` **Problem**: Duplicate functionality or conflicts **Cause**: Multiple versions of the same file **Solution**: Remove all duplicates, keep only files in correct locations ### 8.2 File Organization Audit Script Create this script to check file organization: ```bash #!/bin/bash # File: check-organization.sh echo "=== ZitiNexus UI File Organization Audit ===" # Check for duplicate PHP files echo "Checking for duplicate PHP files..." if [ -f "UI/index.php" ]; then echo "❌ FOUND: UI/index.php (should be removed - use public/index.php)" fi if [ -f "UI/dashboard.php" ]; then echo "❌ FOUND: UI/dashboard.php (should be removed - use public/dashboard.php)" fi if [ -d "UI/testfiles" ]; then echo "❌ FOUND: UI/testfiles/ directory (should be removed in production)" fi # Check required structure echo "Checking required directory structure..." [ -d "UI/public" ] && echo "✅ UI/public/ exists" || echo "❌ UI/public/ missing" [ -d "UI/includes" ] && echo "✅ UI/includes/ exists" || echo "❌ UI/includes/ missing" [ -d "UI/public/assets" ] && echo "✅ UI/public/assets/ exists" || echo "❌ UI/public/assets/ missing" echo "=== Audit Complete ===" ``` --- ## 9. EMERGENCY RECOVERY PROCEDURES ### 9.1 If System Breaks Due to File Organization Issues 1. **Stop web server**: ```bash sudo systemctl stop apache2 # or nginx ``` 2. **Remove all duplicate files**: ```bash rm -f UI/index.php rm -f UI/dashboard.php rm -rf UI/testfiles/ ``` 3. **Verify correct structure exists**: ```bash ls -la UI/public/ ls -la UI/includes/ ``` 4. **Fix file permissions**: ```bash sudo chown -R www-data:www-data /var/www/ziti-enrollment sudo chmod -R 755 /var/www/ziti-enrollment ``` 5. **Restart web server**: ```bash sudo systemctl start apache2 # or nginx ``` ### 9.2 Backup Strategy **Before making changes**: ```bash # Create backup tar -czf ziti-ui-backup-$(date +%Y%m%d-%H%M%S).tar.gz UI/ # Test changes in development environment first ``` --- ## 10. SUMMARY - GOLDEN RULES ### ✅ DO: 1. Keep all public PHP files in `/public/` directory 2. Keep all backend logic in `/includes/` directory 3. Use relative paths correctly based on file location 4. Clean up test files before committing 5. Follow the exact directory structure outlined 6. Test changes in development environment first ### ❌ DON'T: 1. Create duplicate PHP files 2. Put public files outside `/public/` directory 3. Put backend logic outside `/includes/` directory 4. Use absolute paths for includes or assets 5. Leave test files in production 6. Modify file organization without following these guidelines --- **Remember**: The previous system breakage was caused by violating these file organization principles. Following these instructions religiously will prevent similar issues and maintain system stability. **When in doubt**: Refer to this document and the existing working file structure. If you need to create new files, follow the templates and patterns established here.