Notifications Guide

This guide documents all notifications in the client portal system, including triggers, recipients, and redirect URLs.

Notification Types

Notification Details

BackupCompletedNotification

File: app/Notifications/BackupCompletedNotification.php

Sent when a backup job completes successfully. Contains backup name, type, and size.

Triggered by: App\Jobs\CreateBackupJob

Channels: Mail, Database

ImportCompletedNotification

File: app/Notifications/ImportCompletedNotification.php

Sent when a data import job completes. Includes success/error counts.

Triggered by: App\Jobs\ProcessImportJob

Channels: Mail, Database

ProjectCreatedNotification

File: app/Notifications/ProjectCreatedNotification.php

Sent to client users when a new project is created for their account.

Triggered by: App\Services\NotificationService::notifyProjectCreated()

Channels: Mail, Database

ProjectStatusChangedNotification

File: app/Notifications/ProjectStatusChangedNotification.php

Sent to client users when their project status changes (e.g., draft → active → completed).

Triggered by: App\Services\NotificationService::notifyProjectStatusChanged()

Channels: Mail, Database

FileUploadedNotification

File: app/Notifications/FileUploadedNotification.php

Sent to client users when a new file is uploaded to their project (only if file is client-visible).

Triggered by: App\Services\NotificationService::notifyFileUploaded()

Channels: Mail, Database

InvoiceSentNotification

File: app/Notifications/InvoiceSentNotification.php

Sent to client users when an invoice is marked as sent.

Triggered by:

• App\Services\NotificationService::notifyInvoiceSent()
• App\Services\BulkOperationService (bulk invoice sending)

Channels: Mail, Database

InvoiceOverdueNotification

File: app/Notifications/InvoiceOverdueNotification.php

Sent to both client users and all admins when an invoice becomes overdue.

Triggered by: App\Services\NotificationService::notifyInvoiceOverdue()

Channels: Mail, Database

InvoicePaidNotification

File: app/Notifications/InvoicePaidNotification.php

Sent to all admin users when an invoice is marked as paid.

Triggered by: App\Services\NotificationService::notifyInvoicePaid()

Channels: Database only

InvoiceReminderNotification

File: app/Notifications/InvoiceReminderNotification.php

Sent to client users as a reminder about upcoming invoice due dates.

Triggered by:

• App\Jobs\SendInvoiceRemindersJob (scheduled)
• App\Services\NotificationService::notifyInvoiceReminder()

Channels: Mail, Database

InfectedFileNotification

File: app/Notifications/InfectedFileNotification.php

Sent to all admin users when a virus scan detects malware in an uploaded file.

Triggered by: App\Services\VirusScanService::notifyAdmins()

Channels: Mail, Database

ApprovalRequestNotification

File: app/Notifications/ApprovalRequestNotification.php

Sent to designated approvers when a workflow requires approval.

Triggered by: App\Services\Workflow\Actions\RequestApprovalActionHandler

Channels: Mail, Database

WorkflowNotification

File: app/Notifications/WorkflowNotification.php

Generic notification sent by workflow actions. Can be configured with custom title/message.

Triggered by: App\Services\Workflow\Actions\SendNotificationActionHandler

Channels: Mail, Database

Dynamic URL Resolution:

• Project subject → /admin/projects/{id}
• Invoice subject → /admin/invoices/{id}
• Client subject → /admin/clients/{id}

Trigger Locations

NotificationService

File: app/Services/NotificationService.php

Central service for dispatching notifications. Called from controllers when actions occur.

$notificationService->notifyProjectCreated($project);
$notificationService->notifyProjectStatusChanged($project, $oldStatus, $newStatus);
$notificationService->notifyFileUploaded($file);
$notificationService->notifyInvoiceSent($invoice);
$notificationService->notifyInvoiceOverdue($invoice);
$notificationService->notifyInvoicePaid($invoice);
$notificationService->notifyInvoiceReminder($invoice);

RealtimeNotificationService

File: app/Services/RealtimeNotificationService.php

Handles real-time notification delivery via WebSockets (Laravel Reverb).

$realtimeService->notify($user, $notification);
$realtimeService->notifyMany($users, $notification);

Queued Jobs

• CreateBackupJob - Dispatches BackupCompletedNotification
• ProcessImportJob - Dispatches ImportCompletedNotification
• SendInvoiceRemindersJob - Dispatches InvoiceReminderNotification
• SendNotificationJob - Generic job for queuing any notification

Services

• VirusScanService - Dispatches InfectedFileNotification
• BulkOperationService - Dispatches InvoiceSentNotification

Workflow Actions

• SendNotificationActionHandler - Dispatches WorkflowNotification
• RequestApprovalActionHandler - Dispatches ApprovalRequestNotification

Real-Time Notifications

All notifications are broadcast in real-time via Laravel Reverb WebSockets. The frontend receives notifications on a private channel (App.Models.User.{id}) and displays:

1. Toast notification - Appears briefly in the corner
2. Bell badge - Red indicator showing unread count
3. Dropdown list - Shows recent notifications

See DEPLOYMENT.md for Reverb configuration.

Adding New Notifications

1. Create notification class in app/Notifications/
2. Include url field in toArray() method for redirect support
3. Use RealtimeNotificationService for real-time delivery
4. Add to this documentation

Example:

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;

class MyNewNotification extends Notification
{
    public function via(object $notifiable): array
    {
        return ['mail', 'database'];
    }

    public function toArray(object $notifiable): array
    {
        return [
            'type' => 'my_notification',
            'message' => 'Something happened',
            'url' => route('admin.something.show', $this->model),
        ];
    }
}

Dispatch with real-time:

use App\Services\RealtimeNotificationService;

$service = app(RealtimeNotificationService::class);
$service->notify($user, new MyNewNotification($model));