# CuraHealthLine Admin Backend - Implementation Guide

## Overview
Complete administrative backend for managing the CuraHealthLine platform with role-based access control, comprehensive CRUD operations, and activity logging.

## System Architecture

### Technology Stack
- **Framework**: Laravel 12.40.2
- **PHP**: 8.2.12
- **Database**: SQLite
- **Frontend**: TailwindCSS, Alpine.js, Chart.js 4.4.0
- **Authentication**: Multi-guard system (admin + web)

### Admin Roles
1. **super_admin** - Full system access
2. **operations_admin** - Operations management
3. **moderator** - Content moderation
4. **employer_manager** - Employer relations
5. **finance_admin** - Financial operations

## Implemented Phases (1-6)

### Phase 1: Admin Authentication Foundation ✅
**Files Created:**
- `database/migrations/*_create_admins_table.php`
- `database/migrations/*_create_admin_activity_logs_table.php`
- `app/Models/Admin.php` - Role checking, permissions
- `app/Models/AdminActivityLog.php` - Activity tracking with static helper
- `app/Http/Middleware/AdminAuth.php` - Authentication + role-based access
- `app/Http/Controllers/Admin/AuthController.php` - Login/logout with logging
- `routes/admin.php` - Complete route structure
- `config/auth.php` - Updated with admin guard/provider

**Features:**
- Separate admin authentication guard
- Role-based middleware (`admin:super_admin,moderator`)
- Activity logging helper: `AdminActivityLog::log()`
- Password hashing with bcrypt
- Remember me functionality

### Phase 2: Admin Layout & Views ✅
**Files Created:**
- `resources/views/admin/layouts/app.blade.php` - Main layout with sidebar
- `resources/views/admin/layouts/guest.blade.php` - Login layout
- `resources/views/admin/auth/login.blade.php` - Login form

**Features:**
- Responsive sidebar navigation with icons
- Top navigation bar with profile dropdown
- Breadcrumb support
- Flash message display (success/error/status)
- Active menu highlighting
- Mobile-responsive hamburger menu

### Phase 3: Dashboard with KPIs ✅
**Files Created:**
- `app/Http/Controllers/Admin/DashboardController.php`
- `app/Services/Admin/DashboardStatsService.php`
- `resources/views/admin/dashboard/index.blade.php`

**Features:**
- 6 KPI cards: Users, Nurses, Employers, Jobs, Posts, Revenue
- Growth indicators with percentage changes
- Chart.js line chart (30-day trends)
- Pending verification queues (nurses, employers, jobs)
- Recent activity feed (latest 10 activities)
- Quick action buttons

### Phase 4: Nurses Management ✅
**Controller:** `app/Http/Controllers/Admin/NurseController.php`

**Methods:**
- `index()` - Search, filters (status/specialty/license/NCLEX), sorting, pagination
- `show()` - Profile with stats, applications, documents
- `toggleActive()` - Toggle is_active status
- `destroy()` - Delete nurse + related data
- `export()` - CSV export (11 columns)

**Views:**
- `resources/views/admin/nurses/index.blade.php` - Listing with filters
- `resources/views/admin/nurses/show.blade.php` - Detailed profile

**Routes:**
```php
GET    /admin/nurses
GET    /admin/nurses/export
GET    /admin/nurses/{nurse}
PATCH  /admin/nurses/{nurse}/toggle-status
DELETE /admin/nurses/{nurse}
```

### Phase 5: Employers Management ✅
**Controller:** `app/Http/Controllers/Admin/EmployerController.php`

**Methods:**
- `index()` - Search, filters (status/verified/risk), sorting
- `show()` - Profile with stats, jobs, reports
- `toggleActive()` - Toggle active/suspended status
- `verify()` - Grant/revoke verification
- `destroy()` - Delete employer + related data
- `export()` - CSV export (14 columns)

**Views:**
- `resources/views/admin/employers/index.blade.php` - Listing with filters
- `resources/views/admin/employers/show.blade.php` - Detailed profile

**Routes:**
```php
GET    /admin/employers
GET    /admin/employers/export
GET    /admin/employers/{employer}
PATCH  /admin/employers/{employer}/toggle-status
PATCH  /admin/employers/{employer}/verify
DELETE /admin/employers/{employer}
```

**Key Features:**
- Risk scoring display (low/medium/high)
- Verification workflow with timestamps
- Document management
- Ratings and reports tracking

### Phase 6: Jobs Management ✅
**Controller:** `app/Http/Controllers/Admin/JobController.php`

**Methods:**
- `index()` - Search, filters (status/type/mode/visa), sorting
- `show()` - Details with applications breakdown
- `approve()` - Approve pending jobs
- `toggleStatus()` - Toggle active/closed status
- `destroy()` - Delete job + applications
- `export()` - CSV export (12 columns)

**Views:**
- `resources/views/admin/jobs/index.blade.php` - Listing with filters
- `resources/views/admin/jobs/show.blade.php` - Detailed view

**Routes:**
```php
GET    /admin/jobs
GET    /admin/jobs/export
GET    /admin/jobs/{job}
PATCH  /admin/jobs/{job}/approve
PATCH  /admin/jobs/{job}/toggle-status
DELETE /admin/jobs/{job}
```

**Key Features:**
- Approval workflow for pending jobs
- Benefits and perks display
- Application statistics
- Salary range filtering

## Common Patterns

### Activity Logging
All state-changing operations log activity:
```php
AdminActivityLog::log(
    'action_type',
    'Description of action',
    'ModelName',
    $modelId
);
```

### Search Implementation
```php
if (request('search')) {
    $search = request('search');
    $query->where(function($q) use ($search) {
        $q->where('field1', 'like', "%{$search}%")
          ->orWhere('field2', 'like', "%{$search}%");
    });
}
```

### Filter Pattern
```php
if (request('filter_name')) {
    $query->where('field', request('filter_name'));
}
```

### Export Pattern
```php
$callback = function() use ($data) {
    $file = fopen('php://output', 'w');
    fputcsv($file, ['Header1', 'Header2']);
    foreach ($data as $item) {
        fputcsv($file, [$item->field1, $item->field2]);
    }
    fclose($file);
};

return response()->stream($callback, 200, $headers);
```

### Transaction Pattern
```php
try {
    \DB::beginTransaction();
    
    // Delete related data
    $model->relatedData()->delete();
    
    // Delete main model
    $model->delete();
    
    // Log activity
    AdminActivityLog::log(...);
    
    \DB::commit();
    return redirect()->back()->with('status', 'Success');
} catch (\Exception $e) {
    \DB::rollBack();
    return redirect()->back()->with('error', $e->getMessage());
}
```

## Pending Phases (7-13)

### Phase 7: NurseConnect Posts Management
- Content moderation queue
- Flagged posts review
- Post analytics
- Comment moderation
- Trending topics
- Spam detection

### Phase 8: Messaging & Reports System
- Message monitoring
- Report queue (users/jobs/posts)
- Investigation tools
- Resolution workflows
- Ban/warn actions

### Phase 9: Reputation Center
- Reputation score management
- Badge assignment
- Achievement tracking
- Manual adjustments

### Phase 10: CMS (Content Management)
- Pages editor
- Blog posts
- FAQs
- Help articles
- Email templates
- Media library

### Phase 11: Taxonomy Management
- Specialties CRUD
- License types
- Locations
- Benefits
- Skills
- Certifications

### Phase 12: Settings & Configuration
- System settings
- Email configuration
- Payment settings
- API keys
- Maintenance mode
- Backup/restore

### Phase 13: Admin Users & Audit Logs
- Admin user CRUD
- Role assignment
- 2FA setup
- Activity log viewer with filters
- Security monitoring

## Security Features

1. **Authentication**
   - Separate admin guard
   - Session-based authentication
   - Remember me tokens
   - Password hashing

2. **Authorization**
   - Role-based access control
   - Middleware protection
   - Method-level permissions

3. **Activity Tracking**
   - All state changes logged
   - User identification
   - Timestamp tracking
   - Action descriptions

4. **CSRF Protection**
   - All forms protected
   - Token validation
   - Method spoofing for REST

## API Endpoints

All admin routes are prefixed with `/admin` and require authentication:

```
GET     /admin/login (guest only)
POST    /admin/login (guest only)
POST    /admin/logout

GET     /admin/dashboard
GET     /admin/nurses
GET     /admin/employers
GET     /admin/jobs
```

## Database Schema

### admins
- id, name, email, password, role, remember_token, created_at, updated_at

### admin_activity_logs
- id, admin_id, action, description, model_type, model_id, ip_address, user_agent, created_at

## Testing Credentials

**Super Admin:**
- Email: admin@curahealthline.com
- Password: AdminPass123!
- Role: super_admin

## Best Practices

1. **Always use activity logging** for state changes
2. **Use transactions** for multi-step operations
3. **Eager load relationships** to avoid N+1 queries
4. **Validate user input** before processing
5. **Use route model binding** for cleaner code
6. **Keep controllers thin** - use services for complex logic
7. **Consistent naming** - follow Laravel conventions
8. **Add breadcrumbs** for better navigation
9. **Flash messages** for user feedback
10. **Export functionality** for all listings

## Performance Considerations

1. **Pagination**: 20 items per page default
2. **Eager Loading**: Load relationships efficiently
3. **Query Optimization**: Use indexes on searchable fields
4. **Caching**: Consider caching stats for dashboard
5. **Chunking**: For large exports, consider chunking

## Maintenance

### Activity Log Cleanup
Recommend cleaning old logs periodically:
```php
AdminActivityLog::where('created_at', '<', now()->subMonths(6))->delete();
```

### Session Management
Configure session lifetime in `.env`:
```
SESSION_LIFETIME=120
```

## Troubleshooting

### Login Issues
1. Check admin exists in database
2. Verify password hash
3. Check session configuration
4. Clear cache: `php artisan cache:clear`

### Permission Denied
1. Verify user role
2. Check middleware configuration
3. Review route protection

### Activity Log Not Recording
1. Check AdminActivityLog model
2. Verify database connection
3. Check log table structure

## Future Enhancements

1. **Two-Factor Authentication (2FA)**
2. **Advanced Filtering** - Saved filters
3. **Bulk Operations** - Mass actions
4. **API Access** - RESTful API for mobile
5. **Real-time Notifications** - WebSocket integration
6. **Advanced Analytics** - More detailed insights
7. **Data Visualization** - More chart types
8. **Automated Reports** - Scheduled exports
9. **Audit Trail** - Enhanced security logging
10. **Custom Dashboards** - User-configurable widgets

## Support

For issues or questions:
- Review activity logs for errors
- Check Laravel logs: `storage/logs/laravel.log`
- Verify database connections
- Check route configuration

---

**Version**: 1.0.0  
**Last Updated**: December 2, 2025  
**Status**: Phases 1-6 Complete (50% of total system)