6.7 KiB

Raw Blame History

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:

Backend Logic: Add to appropriate file in includes/
Frontend Pages: Create/modify files in public/
Assets: Add to public/assets/
Testing: Create test files in test/

When Creating New Pages:

Create in public/ directory ONLY
Use relative paths for includes: require_once '../includes/auth.php'
Use relative paths for assets: href="assets/css/style.css"
Test thoroughly before committing

When Debugging:

Create debug files in test/ directory
Use descriptive names: test/debug-enrollment-flow.php
Remove or move to test after debugging
Never commit debug files to main directories

🔧 Path Reference Guide

For Files in `public/` Directory:

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

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

Creating files in wrong directory
- Always create user-facing files in public/
- Always create backend logic in includes/
Leaving debug files in production directories
- Move all debug files to test/ directory
- Clean up after debugging sessions
Inconsistent path references
- Use correct relative paths based on file location
- Test all includes and asset references
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/`:

require_once '../includes/auth.php';
require_once '../includes/config.php';
require_once '../includes/enrollment.php';

Asset Paths from `public/`:

<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.

6.7 KiB Raw Blame History