# Notification & Messaging System Documentation

## Overview
Comprehensive notification and messaging system for nurses, employers, and admins across the CURA platform.

## Features Implemented

### 1. Database Structure
- **Notifications Table**: Stores all system notifications
  - `user_id`: Recipient of the notification
  - `sender_id`: User who triggered the notification (optional)
  - `type`: Category (message, connection_request, application_status, etc.)
  - `title`: Notification headline
  - `body`: Detailed message
  - `data`: JSON field for additional contextual data
  - `read_at`: Timestamp when read (null if unread)
  - `action_url`: Link to relevant page
  - `icon`: Emoji or icon identifier

### 2. Notification Types

#### For Nurses:
- **message**: New message received
- **connection_request**: New connection request
- **connection_accepted**: Connection request accepted
- **application_status**: Job application status update
- **new_job**: New job posting matching criteria

#### For Employers:
- **new_application**: Nurse applied to job posting
- **message**: New message received

#### For Admins:
- **new_user**: New user registration
- **verification_request**: Employer verification request

### 3. NotificationService Methods

```php
// Message notifications
notifyNewMessage($recipient, $sender, $conversationId, $preview)

// Connection notifications
notifyConnectionRequest($recipient, $requester)
notifyConnectionAccepted($recipient, $accepter)

// Application notifications
notifyApplicationStatus($nurse, $jobTitle, $status, $applicationId)
notifyNewApplication($employer, $nurse, $jobTitle, $jobId)

// Job notifications
notifyNewJobPosting($nurseIds, $jobTitle, $location, $jobId)

// Admin notifications
notifyAdminNewUser($admin, $newUser)
notifyAdminVerificationRequest($admin, $employer)

// Utility methods
getUnreadCount($user)
markAllAsRead($user)
getRecent($user, $limit = 10)
cleanupOldNotifications($daysOld = 30)
```

### 4. User Interface Components

#### Notification Bell Dropdown
- Location: Navigation bar (all users)
- Shows recent 5 notifications
- Real-time unread count badge
- Auto-polls every 30 seconds
- Quick "Mark All as Read" action

#### Notifications Page
- Full list with pagination
- Filter by read/unread
- Individual notification actions:
  - Mark as read
  - Delete
  - View details (redirects to action_url)
- Bulk "Mark All as Read" button

### 5. Routes

```php
GET  /notifications                    - List all notifications
GET  /notifications/{notification}      - View and redirect
POST /notifications/{notification}/read - Mark as read
POST /notifications/mark-all-read      - Mark all as read
GET  /notifications/unread-count       - Get unread count (AJAX)
DELETE /notifications/{notification}    - Delete notification
```

### 6. Integration Points

#### MessageController
- Sends notification when message is sent
- Notifies all other conversation participants

#### ConnectionController
- Sends notification on connection request
- Sends notification when request is accepted

#### ApplicationController (Ready for integration)
- Notify nurse on status change
- Notify employer on new application

## Usage Examples

### Send a Custom Notification
```php
use App\Services\NotificationService;

$notificationService = app(NotificationService::class);

$notificationService->create([
    'user_id' => $userId,
    'type' => 'custom_type',
    'title' => 'Your Title',
    'body' => 'Your message body',
    'action_url' => route('some.route'),
    'icon' => '🎉',
]);
```

### Check Unread Count
```php
$count = auth()->user()->unreadNotifications()->count();
```

### Get Recent Notifications
```php
$notifications = auth()->user()
    ->notifications()
    ->with('sender')
    ->latest()
    ->limit(10)
    ->get();
```

## UI Components

### Include Notification Dropdown in Layout
```blade
<!-- In your navigation blade file -->
<x-notification-dropdown />
```

### Notification Page Link
```blade
<a href="{{ route('notifications.index') }}">View All Notifications</a>
```

## Testing

### Run the Notification Seeder
```bash
php artisan db:seed --class=NotificationSeeder
```

This creates 7 sample notifications for the current user including:
- 2 unread notifications (connection request, message)
- 5 read notifications (various types)

## Cleanup

### Automated Cleanup (Scheduled)
Add to `app/Console/Kernel.php`:
```php
protected function schedule(Schedule $schedule)
{
    // Clean up notifications older than 30 days
    $schedule->call(function () {
        app(NotificationService::class)->cleanupOldNotifications(30);
    })->daily();
}
```

## Security

- All notification routes require authentication
- Users can only access their own notifications
- XSS protection via Blade escaping
- CSRF protection on all POST/DELETE requests

## Future Enhancements

1. **Real-time Notifications**: Integrate Laravel Echo + Pusher/Reverb
2. **Email Notifications**: Send email for important notifications
3. **Push Notifications**: Browser push notifications
4. **Notification Preferences**: User settings for notification types
5. **Notification Grouping**: Group similar notifications
6. **Rich Notifications**: Attachments, images, interactive actions

## Performance Considerations

- Indexed queries on user_id and read_at
- Pagination for notification lists
- Eager loading of relationships
- Automatic cleanup of old notifications
- Efficient AJAX polling (30-second intervals)

## Styling

The notification UI uses Tailwind CSS with:
- Gradient backgrounds
- Smooth transitions
- Unread highlighting (brand color)
- Responsive design
- Hover effects
- Icons and emojis