12 KiB

Raw Blame History

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
/**
 * [File Description]
 */

// Include backend logic (ALWAYS relative from public directory)
require_once '../includes/auth.php';
require_once '../includes/config.php';

// Authentication check (MANDATORY for protected pages)
if (!isAuthenticated() || !isSessionValid()) {
    header('Location: index.php?error=session_expired');
    exit;
}

// Your page logic here...
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?php echo APP_NAME; ?> - [Page Title]</title>
    <!-- ALWAYS use relative paths for assets -->
    <link rel="stylesheet" href="assets/css/style.css">
</head>
<body>
    <!-- Your HTML here -->
    <script src="assets/js/app.js"></script>
</body>
</html>

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
/**
 * [File Description]
 * 
 * This file contains backend logic and should never be accessed directly.
 */

// Prevent direct access
if (!defined('APP_NAME')) {
    http_response_code(403);
    exit('Direct access forbidden');
}

// Your backend logic here...

2.3 Asset Files

Location: /public/assets/ directory structure

Rules:

CSS files: /public/assets/css/
JavaScript files: /public/assets/js/
Images: /public/assets/images/
Use relative paths in public PHP files: assets/css/style.css

3. INCLUDE PATH STANDARDS

3.1 From Public Directory Files

// ✅ CORRECT - From /public/ files
require_once '../includes/config.php';
require_once '../includes/auth.php';
require_once '../includes/api_client.php';
require_once '../includes/enrollment.php';

3.2 From Include Files (Cross-includes)

// ✅ CORRECT - From /includes/ files including other includes
require_once __DIR__ . '/config.php';
require_once __DIR__ . '/auth.php';

3.3 Asset Paths in Public Files

// ✅ CORRECT - In public PHP files
<link rel="stylesheet" href="assets/css/style.css">
<script src="assets/js/app.js"></script>
<img src="assets/images/logo.png" alt="Logo">

4. TESTING AND DEVELOPMENT WORKFLOW

4.1 Development Testing

For testing new features:

✅ Create test files in /testfiles/ directory
✅ Use clear naming: test-[feature-name].php
✅ Document what you're testing
✅ ALWAYS CLEAN UP after testing

4.2 Test File Cleanup (MANDATORY)

Before committing code:

# 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:

<VirtualHost *:80>
    ServerName ziti-enrollment.local
    DocumentRoot /var/www/ziti-enrollment/public  # ← CRITICAL: Points to public/
    
    <Directory /var/www/ziti-enrollment/public>
        AllowOverride All
        Require all granted
        DirectoryIndex index.php
    </Directory>
</VirtualHost>

Nginx Configuration:

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
/**
 * [File Description]
 * 
 * [Detailed description of file purpose]
 * 
 * @author [Your Name]
 * @version 1.0.0
 */

Error Handling:

// ✅ ALWAYS use proper error handling
try {
    // Your code here
} catch (Exception $e) {
    logMessage('ERROR', 'Operation failed: ' . $e->getMessage());
    // Handle error appropriately
}

Input Sanitization:

// ✅ ALWAYS sanitize user input
$userInput = sanitizeInput($_POST['field'] ?? '');

6.2 Security Best Practices

Authentication Checks:

// ✅ MANDATORY for all protected pages
if (!isAuthenticated() || !isSessionValid()) {
    header('Location: index.php?error=session_expired');
    exit;
}

CSRF Protection:

// ✅ For all forms
<input type="hidden" name="csrf_token" value="<?php echo generateCSRFToken(); ?>">

// ✅ 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

# 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:

#!/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

Stop web server:

sudo systemctl stop apache2  # or nginx

Remove all duplicate files:

rm -f UI/index.php
rm -f UI/dashboard.php
rm -rf UI/testfiles/

Verify correct structure exists:
```
ls -la UI/public/
ls -la UI/includes/
```

Fix file permissions:

sudo chown -R www-data:www-data /var/www/ziti-enrollment
sudo chmod -R 755 /var/www/ziti-enrollment

Restart web server:

sudo systemctl start apache2  # or nginx

9.2 Backup Strategy

Before making changes:

# 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:

Keep all public PHP files in /public/ directory
Keep all backend logic in /includes/ directory
Use relative paths correctly based on file location
Clean up test files before committing
Follow the exact directory structure outlined
Test changes in development environment first

❌ DON'T:

Create duplicate PHP files
Put public files outside /public/ directory
Put backend logic outside /includes/ directory
Use absolute paths for includes or assets
Leave test files in production
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.

12 KiB Raw Blame History

ZitiNexus Router Enrollment UI - Development Instructions

⚠️ CRITICAL: File Organization Rules

1. STRICT FILE ORGANIZATION STRUCTURE

1.1 Directory Structure (MANDATORY)

1.2 FORBIDDEN Practices

2. FILE CREATION GUIDELINES

2.1 Public-Facing PHP Files

2.2 Backend Logic Files

2.3 Asset Files

3. INCLUDE PATH STANDARDS

3.1 From Public Directory Files

3.2 From Include Files (Cross-includes)

3.3 Asset Paths in Public Files

4. TESTING AND DEVELOPMENT WORKFLOW

4.1 Development Testing

4.2 Test File Cleanup (MANDATORY)

4.3 Pre-Commit Checklist

5. WEB SERVER CONFIGURATION

5.1 Document Root Configuration

5.2 Security Benefits

6. CODE QUALITY STANDARDS

6.1 PHP Coding Standards

6.2 Security Best Practices

7. DEPLOYMENT GUIDELINES

7.1 Production Deployment Checklist

7.2 File Permissions

8. TROUBLESHOOTING FILE ORGANIZATION ISSUES

8.1 Common Problems and Solutions

8.2 File Organization Audit Script

9. EMERGENCY RECOVERY PROCEDURES

9.1 If System Breaks Due to File Organization Issues

9.2 Backup Strategy

10. SUMMARY - GOLDEN RULES

✅ DO:

❌ DON'T:

12 KiB

Raw Blame History