# Admin Management System - Access Control

## System Overview

The CURA HealthLine admin management system provides comprehensive role-based access control (RBAC) with multiple admin roles and granular permission management. Super administrators can manage admin accounts, assign roles, and control access levels through a dedicated dashboard.

## Features Implemented

### 1. Admin Roles & Hierarchy

The system supports 5 distinct admin roles with different access levels:

| Role | Level | Description | Key Capabilities |
|------|-------|-------------|-------------------|
| **Super Administrator** | 5 | Full system access and control | Manage admins, edit roles, all permissions |
| **Operations Administrator** | 4 | Manage platform operations and users | Manage nurses, employers, jobs, moderation |
| **Finance Administrator** | 3 | Financial management and reporting | Transaction management, financial reports |
| **Employer Manager** | 2 | Employer account and job management | Manage employers and their job postings |
| **Content Moderator** | 1 | Content moderation | Moderate content, view reports |

### 2. Permission System

**75+ Granular Permissions** organized by category:

- **Admin Management**: manage_admins, create_admin, edit_admin, delete_admin, view_admin_logs
- **System Settings**: manage_system_settings, view_system_settings, manage_database, manage_backups
- **Nurses Management**: manage, create, edit, delete, view, verify credentials, approve, suspend
- **Employers Management**: manage, create, edit, delete, view, approve, suspend
- **Jobs Management**: manage, create, edit, delete, view, approve, suspend
- **Bookings & Applications**: manage, view, approve, reject
- **Content Moderation**: moderate_content, flag_content, remove_content, ban_user
- **Reports & Analytics**: view_reports, view_analytics, export_reports
- **Communication**: send_notifications, manage_email_templates
- **Dashboard**: view_dashboard

### 3. Access Control Management Dashboard

Located at `/admin/access` - Super admin only

Features:
- **Roles & Permissions Overview**: Visual display of all roles with their modules and permissions
- **Role Editor**: View and manage permissions for each role
- **Admin Assignment**: Assign roles and status to individual admins
- **Access Report**: Comprehensive report of all roles, permissions, and admin assignments
- **Audit Logs**: Track all admin-related activities
- **CSV Export**: Export access control report for documentation

## File Structure

```
app/
├── Http/Controllers/Admin/
│   └── AdminAccessController.php          # Access control management controller
├── Services/
│   └── AdminPermissionService.php         # Permission checking and role utilities
└── Models/
    └── Admin.php                          # Admin model with role methods

config/
└── admin_permissions.php                  # Role and permission configuration

database/migrations/
├── 2025_12_02_000001_create_admins_table.php
├── 2025_12_02_000002_create_admin_activity_logs_table.php
└── 2025_12_04_000001_create_admin_roles_table.php

resources/views/admin/
├── access/
│   ├── index.blade.php                   # Access control dashboard
│   ├── edit-role.blade.php              # Role permission editor
│   ├── edit-admin.blade.php             # Admin assignment editor
│   ├── report.blade.php                 # Comprehensive access report
│   └── audit-logs.blade.php             # Activity audit logs
├── admins/
│   ├── index.blade.php                  # Admin list
│   ├── create.blade.php                 # Create new admin
│   ├── edit.blade.php                   # Edit admin details
│   ├── show.blade.php                   # View admin details
│   └── confirm-delete.blade.php         # Delete confirmation
└── partials/
    └── sidebar.blade.php                # Admin sidebar with access control link

routes/
└── admin.php                            # Admin routes including access management
```

## Routes

### Access Control Routes (Super Admin Only)

```
GET    /admin/access                      # Access control dashboard
GET    /admin/access/report               # Comprehensive access report
GET    /admin/access/report/export        # Download CSV report
GET    /admin/access/roles/{role}/edit    # Edit role permissions
PATCH  /admin/access/roles/{role}         # Update role permissions
GET    /admin/access/admins/{admin}/edit  # Edit admin permissions
PATCH  /admin/access/admins/{admin}       # Update admin role/status
GET    /admin/access/audit-logs           # View admin activity logs
```

### Admin Management Routes (Super Admin Only)

```
GET    /admin/admins                      # List all admins
GET    /admin/admins/create               # Create new admin form
POST   /admin/admins                      # Store new admin
GET    /admin/admins/{admin}              # View admin details
GET    /admin/admins/{admin}/edit         # Edit admin form
PATCH  /admin/admins/{admin}              # Update admin
DELETE /admin/admins/{admin}              # Delete admin
PATCH  /admin/admins/{admin}/toggle-status  # Toggle admin status
GET    /admin/admins/{admin}/verify-permissions  # Verify permissions (API)
```

## Key Services & Classes

### AdminPermissionService

Utility class for permission checking:

```php
// Get all permissions
AdminPermissionService::getAllPermissions();

// Get all roles
AdminPermissionService::getAllRoles();

// Get role configuration
AdminPermissionService::getRoleConfig('super_admin');

// Get role modules
AdminPermissionService::getRoleModules('operations_admin');

// Get role permissions
AdminPermissionService::getRolePermissions('moderator');

// Check if role can manage resource
AdminPermissionService::canManage('employer_manager', 'employers');

// Check module access
AdminPermissionService::hasModuleAccess('finance_admin', 'finances');

// Get role hierarchy
AdminPermissionService::getRoleHierarchy();
```

### Admin Model Methods

```php
$admin->isSuperAdmin();
$admin->isOperationsAdmin();
$admin->isModerator();
$admin->isEmployerManager();

// Check permission
$admin->hasPermission('manage_nurses');

// Get role permissions
$permissions = AdminPermissionService::getRolePermissions($admin->role);
```

## Usage Examples

### Checking Admin Permissions

```php
// In controller
if (auth('admin')->user()->hasPermission('manage_employers')) {
    // Allow access
}

// In blade template
@if(auth('admin')->user()->hasPermission('view_reports'))
    <!-- Show reports link -->
@endif
```

### Authorizing Actions

```php
// Use AdminAuthorization trait
use App\Traits\AdminAuthorization;

public function destroy(Admin $admin)
{
    $this->authorizePermission('delete_admin');
    // Safe to proceed
}
```

### Managing Admin Roles

1. Navigate to `/admin/access` as Super Admin
2. View all roles in the "Roles & Permissions" tab
3. Click "View Permissions" to see/edit role details
4. Click "Edit Permissions" on an admin to change their role/status

## Configuration

Edit `config/admin_permissions.php` to:
- Add new permissions
- Modify role capabilities
- Change role descriptions
- Update module access

Example:
```php
'permissions' => [
    'new_permission' => ['super_admin', 'operations_admin'],
],

'roles' => [
    'custom_role' => [
        'name' => 'Custom Role',
        'description' => 'Role description',
        'modules' => ['module1', 'module2'],
        'can_edit_roles' => false,
        'can_manage_admins' => false,
    ],
]
```

## Audit Logging

All admin actions are logged in `admin_activity_logs` table:
- Admin creation/modification/deletion
- Role changes
- Permission updates
- Login events

View logs at `/admin/access/audit-logs`

## Security Features

1. **Super Admin Protection**: Only Super Admins can manage other admins
2. **Self-Edit Prevention**: Admins cannot edit their own permissions from access control
3. **Permission Checks**: Every action requires explicit permission grant
4. **Activity Logging**: All administrative actions are recorded
5. **Status Management**: Admins can be suspended without deletion
6. **2FA Support**: Two-factor authentication available for admin accounts

## Testing the System

### Test Admin Account

Use the default admin account created during migration:
- Email: admin@admin.local
- Password: password
- Role: super_admin

### Test Scenarios

1. **Create New Admin**
   - Go to `/admin/admins/create`
   - Assign different roles
   - Verify permissions in access control

2. **Edit Admin Role**
   - Go to `/admin/access`
   - Click "Edit Permissions" on an admin
   - Change role and status
   - Verify changes in audit logs

3. **View Access Report**
   - Go to `/admin/access/report`
   - Review role permissions
   - Export CSV for documentation

4. **Check Audit Logs**
   - Go to `/admin/access/audit-logs`
   - Search for specific actions
   - Verify all changes are recorded

## Future Enhancements

1. **Dynamic Roles**: Store roles in database instead of config
2. **Custom Permissions**: Allow Super Admins to create custom permissions
3. **Permission Groups**: Group related permissions
4. **IP Whitelisting**: Restrict admin access by IP
5. **API Tokens**: Generate API tokens for programmatic access
6. **Single Sign-On**: Integrate with LDAP/SSO systems
7. **Advanced Audit**: Store request details and changes in audit logs

## Support & Documentation

For more information:
- Admin authentication: `/routes/admin.php`
- Permission middleware: `/app/Http/Middleware/CheckAdminRole.php`
- Authorization trait: `/app/Traits/AdminAuthorization.php`

---

**Last Updated**: December 4, 2025
**Version**: 1.0
**Status**: Production Ready