Admin

name	type	size	perms	modified	actions
[parent directory]
copilot-instructions.md	file	9,741 B	0664	2026-06-25 23:50:33	edit

editing: copilot-instructions.md

# GitHub Copilot Instructions for Muhajir Project LMS

**ALWAYS follow these instructions first and fallback to additional search and context gathering ONLY if the information here is incomplete or found to be in error.**

## Project Overview
This is the Muhajir Project Learning Management System (LMS) for Islamic education. It's a hybrid Laravel 10 + React 18 application using Inertia.js for seamless server-side rendering with modern frontend components.

**Technology Stack:**
- **Backend**: Laravel 10 (PHP 8.1+) with Sanctum authentication
- **Frontend**: React 18 + TypeScript with Inertia.js
- **UI**: shadcn/ui components (built on Radix UI primitives) with Tailwind CSS
- **Database**: MySQL (preferred) or SQLite for testing
- **Build Tools**: Vite for asset compilation
- **Rich Text**: TipTap editor for content creation

## CRITICAL Setup Requirements

### Environment Prerequisites
Install these exact versions:
- **PHP**: 8.1 or higher (tested with 8.3.6)
- **Composer**: Latest version
- **Node.js**: 20.x or higher (tested with 20.19.4)
- **npm**: 10.x or higher (tested with 10.8.2)
- **MySQL**: 8.0+ (preferred) or SQLite for basic testing

### Essential Bootstrap Commands

**NEVER CANCEL these commands - set timeouts as specified:**

1. **Copy environment file:**
   ```bash
   cp .env.example .env
   ```

2. **Install PHP dependencies** (3-5 minutes, NEVER CANCEL):
   ```bash
   composer install --no-interaction
   # Timeout: Set to 600+ seconds, may show database connection warnings
   ```

3. **Install Node.js dependencies** (6-30 seconds):
   ```bash
   npm install
   # If TipTap Pro package fails: temporarily remove "@tiptap-pro/extension-file-handler" from package.json
   ```

4. **Generate Laravel application key:**
   ```bash
   php artisan key:generate
   ```

5. **🔴 CRITICAL: Generate Ziggy routes** (ALWAYS run after route changes):
   ```bash
   php artisan ziggy:generate
   # This creates resources/js/ziggy.js - frontend WILL NOT BUILD without this file
   ```

### Database Setup Options

**Option A: MySQL (Recommended for full functionality)**
```bash
# Update .env file:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=your_password

# Run migrations:
php artisan migrate --force
```

**Option B: SQLite (For basic testing only - LIMITED)**
```bash
# Update .env file:
DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database/database.sqlite

# Create database file:
touch database/database.sqlite

# ⚠️ IMPORTANT: Multiple migrations WILL FAIL with SQLite due to foreign key modifications
# SQLite does not support dropping foreign keys, which several recent migrations require
# Use MySQL for full functionality and testing
```

## Build and Development Commands

### Production Build (18-25 seconds, NEVER CANCEL)
```bash
npm run build
# Timeout: Set to 120+ seconds
# Creates optimized assets in public/build/
```

### Development Server Options

**Option A: Individual services**
```bash
# Laravel server only:
php artisan serve
# Runs on http://127.0.0.1:8000

# Vite dev server only (for asset compilation):
npm run dev
# Note: May fail in CI environments without LARAVEL_BYPASS_ENV_CHECK=1
```

**Option B: Concurrent development (Recommended)**
```bash
composer run dev
# Starts: Laravel server + queue worker + logs + Vite dev server
# Note: Requires 'concurrently' package: npm install -g concurrently
```

## Testing Commands

### PHPUnit Tests (6-10 seconds, NEVER CANCEL)
```bash
# All tests:
php artisan test
# Timeout: Set to 300+ seconds

# Feature tests only:
php artisan test tests/Feature

# Unit tests only:
php artisan test tests/Unit

# Note: Tests require MySQL for full functionality
```

### Code Quality
```bash
# Laravel Pint (code formatting):
./vendor/bin/pint --test  # Dry run
./vendor/bin/pint         # Apply fixes

# Note: Pint may take 2-3 minutes for full codebase scan
```

## CRITICAL Workflow Requirements

### After Route Changes
**ALWAYS run this command after modifying routes in `routes/web.php` or `routes/api.php`:**
```bash
php artisan ziggy:generate
```
**Without this, the frontend build WILL FAIL.**

### Before Committing Changes
```bash
# 1. Run build to ensure assets compile:
npm run build

# 2. Run tests to check for regressions:
php artisan test

# 3. Format code:
./vendor/bin/pint
```

## Manual Validation Scenarios

**ALWAYS test these scenarios after making changes:**

### 1. Basic Application Startup (TESTED WORKING)
```bash
php artisan serve
# Visit http://127.0.0.1:8000
# Expected: Homepage loads (200 OK status)
# Verify: React/Inertia components render without console errors
```

### 2. Authentication Flow (ROUTES CONFIRMED)
```bash
# Test auth endpoints:
curl -I http://127.0.0.1:8000/login      # Should return 200 OK
curl -I http://127.0.0.1:8000/register   # Should return 200 OK
curl -I http://127.0.0.1:8000/admin      # Should return 302 Found (redirect to login)
```
- Navigate to `/login` page
- Create test user account at `/register`
- Verify login/logout functionality
- Test password reset flow

### 3. Admin Dashboard
- Login as admin user
- Navigate to admin panel (`/admin`) - should redirect if not authenticated
- Verify course management interface loads
- Test user management features

### 4. Course Access
- Login as student user
- Browse available courses
- Test course enrollment workflow
- Verify topic progress tracking functionality

### 5. API Functionality (AUTHENTICATION REQUIRED)
```bash
# Test public API endpoints (may require authentication):
curl -H "Accept: application/json" http://127.0.0.1:8000/api/courses
curl -H "Accept: application/json" http://127.0.0.1:8000/api/health
```

## Common Issues and Solutions

### Build Failures
- **"Could not load /resources/js/ziggy"**: Run `php artisan ziggy:generate` (CRITICAL - build will fail without this)
- **TipTap Pro package fails during npm install**: 
  ```bash
  # Temporarily remove from package.json, install, then restore:
  # Remove line: "@tiptap-pro/extension-file-handler": "^2.17.4",
  npm install
  # Then restore the line and continue without that package if needed
  ```
- **Database connection refused**: Check .env database configuration and ensure database server is running

### Development Server Issues
- **Vite won't start in CI**: Set `LARAVEL_BYPASS_ENV_CHECK=1` in .env file
- **Queue worker errors**: Ensure database is properly configured and migrations have run
- **pail command not found**: This command is from Laravel 11+, expected in Laravel 10 projects
- **Concurrent development fails**: Install concurrently globally: `npm install -g concurrently`

### Database and Migration Issues
- **SQLite migration errors**: 
  ```bash
  # Multiple migrations fail with SQLite due to foreign key modifications
  # Error: "SQLite doesn't support dropping foreign keys"
  # Solution: Use MySQL instead for full functionality
  ```
- **Migration fails with "Connection refused"**: Database server not running or wrong credentials in .env

### Test Failures
- **All tests failing with database errors**: Use MySQL and run migrations first: `php artisan migrate`
- **"BadMethodCallException" during tests**: SQLite incompatibility - switch to MySQL for testing

## Architecture Navigation

### Key Directories
- **Backend Controllers**: `app/Http/Controllers/`
  - `Api/` - REST API endpoints
  - `Backend/` - Admin panel functionality
  - `Frontend/` - Public user-facing features
- **Frontend Components**: `resources/js/`
  - `Pages/` - Inertia.js page components (route-mapped)
  - `components/ui/` - Reusable shadcn/ui components (built on Radix UI)
  - `modules/` - Feature-specific components
- **Database**: `database/migrations/` - Database schema
- **Routes**: `routes/` - API and web routes
- **Views**: `resources/views/` - Blade templates (admin panel)

### Multi-Role System
- **Admin**: Full system access, user management
- **Instructor**: Course creation and management
- **Student/User**: Course enrollment and progress tracking

## Performance Expectations

| Command | Expected Time | Timeout Setting |
|---------|---------------|-----------------|
| `composer install` | 3-5 minutes | 600+ seconds |
| `npm install` | 6-30 seconds | 120+ seconds |
| `npm run build` | 18-25 seconds | 120+ seconds |
| `php artisan test` | 6-10 seconds | 300+ seconds |
| `php artisan migrate` | 10-30 seconds | 120+ seconds |
| `php artisan ziggy:generate` | 1-2 seconds | 30+ seconds |

**🔴 NEVER CANCEL long-running commands - build times are normal for this application size.**

## Emergency Commands

If something breaks during development:
```bash
# Reset environment:
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

# Regenerate critical files:
php artisan ziggy:generate
composer dump-autoload
npm run build
```

## Quick Reference Commands

```bash
# Fresh project setup:
cp .env.example .env && composer install && npm install && php artisan key:generate && php artisan ziggy:generate

# Development workflow:
php artisan serve                    # Start Laravel server
npm run dev                          # Start Vite (may not work in CI)
composer run dev                     # Start all services concurrently

# Build and test:
npm run build                        # Build frontend assets (~18 seconds)
php artisan test                     # Run tests (~6 seconds)
./vendor/bin/pint                    # Format PHP code

# After route changes:
php artisan ziggy:generate           # CRITICAL - always run after route modifications

# Database operations:
php artisan migrate                  # Run migrations
php artisan migrate:fresh --force    # Reset and run all migrations
```

cancel