210 lines
6.7 KiB
Markdown
210 lines
6.7 KiB
Markdown
# ZitiNexus Router Enrollment UI - Development Guidelines
|
|
|
|
This document establishes clear guidelines for maintaining a clean, organized codebase and proper file structure.
|
|
|
|
## 📁 **Project Structure**
|
|
|
|
### **Current Clean Structure:**
|
|
```
|
|
UI/
|
|
├── includes/ # Backend PHP classes and utilities
|
|
│ ├── auth.php # Authentication management
|
|
│ ├── config.php # Configuration and utilities
|
|
│ ├── enrollment.php # Main enrollment logic
|
|
│ └── api_client.php # API communication
|
|
├── public/ # Web-accessible files (DOCUMENT ROOT)
|
|
│ ├── index.php # Login page
|
|
│ ├── dashboard.php # Main dashboard
|
|
│ ├── progress.php # Progress polling endpoint
|
|
│ └── assets/ # Static assets
|
|
│ ├── css/ # Stylesheets
|
|
│ ├── js/ # JavaScript files
|
|
│ └── images/ # Images and icons
|
|
├── test/ # Testing and debugging files
|
|
├── logs/ # Log files (.gitkeep)
|
|
├── temp/ # Temporary files (.gitkeep)
|
|
└── *.md # Documentation files
|
|
```
|
|
|
|
## 🎯 **File Location Rules**
|
|
|
|
### **Rule 1: Public Directory is Primary**
|
|
- **ALL user-accessible files MUST be in `public/` directory**
|
|
- Web server document root should point to `UI/public/`
|
|
- Never create duplicate files in main UI directory
|
|
|
|
### **Rule 2: Single Source of Truth**
|
|
- **Dashboard**: Only `public/dashboard.php` exists
|
|
- **Index/Login**: Only `public/index.php` exists
|
|
- **Progress API**: Only `public/progress.php` exists
|
|
- **Assets**: Only `public/assets/` directory exists
|
|
|
|
### **Rule 3: Backend Logic Separation**
|
|
- **PHP Classes**: Always in `includes/` directory
|
|
- **Configuration**: Always in `includes/config.php`
|
|
- **Authentication**: Always in `includes/auth.php`
|
|
- **Business Logic**: Always in `includes/enrollment.php`
|
|
|
|
### **Rule 4: Testing and Debug Files**
|
|
- **ALL testing files**: Must be in `test/` directory
|
|
- **Debug scripts**: Must be in `test/` directory
|
|
- **Temporary test files**: Must be in `test/` directory
|
|
- **Never leave debug files in main directories**
|
|
|
|
## 🚫 **What NOT to Do**
|
|
|
|
### **❌ NEVER Create Duplicate Files:**
|
|
```
|
|
❌ UI/dashboard.php AND UI/public/dashboard.php
|
|
❌ UI/index.php AND UI/public/index.php
|
|
❌ UI/assets/ AND UI/public/assets/
|
|
❌ UI/progress.php AND UI/public/progress.php
|
|
```
|
|
|
|
### **❌ NEVER Put Debug Files in Main Directories:**
|
|
```
|
|
❌ UI/debug-*.php
|
|
❌ UI/test-*.php
|
|
❌ UI/public/debug-*.php
|
|
❌ UI/public/test-*.php
|
|
```
|
|
|
|
### **❌ NEVER Mix Production and Test Code:**
|
|
```
|
|
❌ Debug code in production files
|
|
❌ Test endpoints in production files
|
|
❌ Console.log statements in production JavaScript
|
|
```
|
|
|
|
## ✅ **Correct Development Workflow**
|
|
|
|
### **When Adding New Features:**
|
|
|
|
1. **Backend Logic**: Add to appropriate file in `includes/`
|
|
2. **Frontend Pages**: Create/modify files in `public/`
|
|
3. **Assets**: Add to `public/assets/`
|
|
4. **Testing**: Create test files in `test/`
|
|
|
|
### **When Creating New Pages:**
|
|
|
|
1. **Create in `public/` directory ONLY**
|
|
2. **Use relative paths for includes**: `require_once '../includes/auth.php'`
|
|
3. **Use relative paths for assets**: `href="assets/css/style.css"`
|
|
4. **Test thoroughly before committing**
|
|
|
|
### **When Debugging:**
|
|
|
|
1. **Create debug files in `test/` directory**
|
|
2. **Use descriptive names**: `test/debug-enrollment-flow.php`
|
|
3. **Remove or move to test after debugging**
|
|
4. **Never commit debug files to main directories**
|
|
|
|
## 🔧 **Path Reference Guide**
|
|
|
|
### **For Files in `public/` Directory:**
|
|
|
|
```php
|
|
// Correct includes from public files
|
|
require_once '../includes/auth.php';
|
|
require_once '../includes/enrollment.php';
|
|
require_once '../includes/config.php';
|
|
|
|
// Correct asset paths in public files
|
|
<link rel="stylesheet" href="assets/css/style.css">
|
|
<script src="assets/js/app.js"></script>
|
|
```
|
|
|
|
### **For Files in `test/` Directory:**
|
|
|
|
```php
|
|
// Correct includes from test files
|
|
require_once '../includes/auth.php';
|
|
require_once '../includes/enrollment.php';
|
|
|
|
// Correct asset paths in test files (if needed)
|
|
<link rel="stylesheet" href="../public/assets/css/style.css">
|
|
```
|
|
|
|
## 📋 **Code Review Checklist**
|
|
|
|
### **Before Committing:**
|
|
|
|
- [ ] No duplicate files between main and public directories
|
|
- [ ] All debug/test files are in `test/` directory
|
|
- [ ] All user-accessible files are in `public/` directory
|
|
- [ ] All includes use correct relative paths
|
|
- [ ] All asset references use correct paths
|
|
- [ ] No console.log or debug statements in production code
|
|
- [ ] File structure follows established conventions
|
|
|
|
### **File Naming Conventions:**
|
|
|
|
- **Production files**: `dashboard.php`, `index.php`, `progress.php`
|
|
- **Test files**: `test-feature-name.php`, `debug-issue-name.php`
|
|
- **Documentation**: `FEATURE_NAME.md` (uppercase)
|
|
- **Scripts**: `script-name.sh` (lowercase with hyphens)
|
|
|
|
## 🎯 **Development Best Practices**
|
|
|
|
### **1. Single Responsibility**
|
|
- Each file should have a single, clear purpose
|
|
- Separate concerns between frontend and backend
|
|
- Keep business logic in `includes/` directory
|
|
|
|
### **2. Consistent Structure**
|
|
- Always follow the established directory structure
|
|
- Use consistent naming conventions
|
|
- Maintain clear separation between production and test code
|
|
|
|
### **3. Clean Codebase**
|
|
- Remove unused files regularly
|
|
- Keep test files organized in `test/` directory
|
|
- Document any deviations from standard structure
|
|
|
|
### **4. Path Management**
|
|
- Use relative paths consistently
|
|
- Test paths work from intended directory structure
|
|
- Avoid hardcoded absolute paths
|
|
|
|
## 🚨 **Common Mistakes to Avoid**
|
|
|
|
1. **Creating files in wrong directory**
|
|
- Always create user-facing files in `public/`
|
|
- Always create backend logic in `includes/`
|
|
|
|
2. **Leaving debug files in production directories**
|
|
- Move all debug files to `test/` directory
|
|
- Clean up after debugging sessions
|
|
|
|
3. **Inconsistent path references**
|
|
- Use correct relative paths based on file location
|
|
- Test all includes and asset references
|
|
|
|
4. **Duplicate functionality**
|
|
- Avoid creating multiple versions of same file
|
|
- Maintain single source of truth for each feature
|
|
|
|
## 📚 **Quick Reference**
|
|
|
|
### **File Locations:**
|
|
- **User Pages**: `public/` only
|
|
- **Backend Logic**: `includes/` only
|
|
- **Assets**: `public/assets/` only
|
|
- **Tests/Debug**: `test/` only
|
|
- **Documentation**: Root UI directory
|
|
|
|
### **Include Paths from `public/`:**
|
|
```php
|
|
require_once '../includes/auth.php';
|
|
require_once '../includes/config.php';
|
|
require_once '../includes/enrollment.php';
|
|
```
|
|
|
|
### **Asset Paths from `public/`:**
|
|
```html
|
|
<link rel="stylesheet" href="assets/css/style.css">
|
|
<script src="assets/js/app.js"></script>
|
|
```
|
|
|
|
Following these guidelines ensures a clean, maintainable, and professional codebase that's easy to understand and extend.
|