Notifications Module

Overview

The notification module provides event-driven alerts through two channels: in-app notifications (stored in database) and email notifications (sent via configured mail transport).

Scope

Feature	Status
In-App Notifications	✅ Implemented
Email Notifications	✅ Implemented
Notification Settings (Admin)	✅ Implemented
Unread Count / Badge	✅ Implemented
Mark as Read (single & bulk)	✅ Implemented
Push Notifications	🔜 Future
SMS Notifications	🔜 Future

Architecture

How Notifications Work

1. A domain event occurs (e.g., employee submits self-assessment).
2. The service layer dispatches a Laravel Notification to the appropriate recipients.
3. Laravel routes the notification through configured channels (database, mail).
4. The database channel creates a record in the notifications table.
5. The mail channel sends an email via the configured SMTP transport.
6. The frontend polls or checks for new notifications on page navigation.

Backend Components

Component	Path	Purpose
Notifications Dir	app/Notifications/	Laravel Notification classes
Notification Settings	Database table	Per-event-type on/off toggles
Mail Templates	resources/views/mail/	Email templates

Notification Classes

Each notification class implements:

• via() — Returns channels (['database', 'mail'])
• toArray() — Data stored in the notifications table
• toMail() — Email content and template

Frontend Components

Component	Path	Purpose
Bell Dropdown	src/components/notifications/	Bell icon with unread count + dropdown
Settings Page	app/dashboard/notification-settings/	Admin notification configuration

Event Types

Event	Notification Class	Recipients
Self-Assessment Submitted	KpiSelfAssessmentSubmitted	Assigned reviewer
Manager Review Submitted	KpiManagerReviewSubmitted	HR users
HR Review Submitted	KpiHrReviewSubmitted	Employee
Evaluation Accepted	KpiEvaluationAccepted	HR users
Evaluation Disputed	KpiEvaluationDisputed	HR users
Probation Review Created	ProbationReviewCreated	Assigned manager
Probation Review Submitted	ProbationReviewSubmitted	HR users
Probation Review Outcome	ProbationReviewOutcome	Manager

Data Model

Notifications Table (Laravel Default)

notifications (
    id          UUID PRIMARY KEY,
    type        VARCHAR,          -- Notification class name
    notifiable_type VARCHAR,      -- 'App\Models\User'
    notifiable_id   BIGINT,       -- User ID
    data        JSON,             -- Notification payload
    read_at     TIMESTAMP NULL,   -- NULL = unread
    created_at  TIMESTAMP,
    updated_at  TIMESTAMP
)

Notification Settings Table

notification_settings (
    id          BIGINT PRIMARY KEY,
    event_type  VARCHAR,          -- Event identifier
    channels    JSON,             -- ['database', 'mail']
    is_active   BOOLEAN,          -- Master toggle
    created_at  TIMESTAMP,
    updated_at  TIMESTAMP
)

API Endpoints

Method	Endpoint	Description
GET	/api/notifications	List user's notifications
GET	/api/notifications/unread-count	Get unread notification count
POST	/api/notifications/{id}/mark-read	Mark single notification as read
POST	/api/notifications/mark-all-read	Mark all as read
GET	/api/notification-settings	Get notification settings
PUT	/api/notification-settings	Update notification settings

Email Configuration

Email notifications use Laravel's mail system. Configure in .env:

MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=2525
MAIL_FROM_ADDRESS=hrms@kingrevolution.com
MAIL_FROM_NAME="King Revolution HRMS"

For local development, use smtp4dev to capture emails without sending them.