Notification Setting
Data Entity
Description
User-level configuration for which notification types and reminder scenarios are enabled. Allows users to opt in or out of non-critical reminders while mandatory notifications (assignment dispatches, security alerts) remain always-on. Coordinators can also configure scenario-specific threshold days. Also stores FCM device token registrations per platform, enabling the backend to deliver push messages to the correct device.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key. UUID v4 generated on insert. | PKrequiredunique |
user_id |
uuid |
Foreign key referencing the users table. Each user owns multiple notification setting records — one per scenario type. | required |
scenario_type |
enum |
Identifies the notification scenario or device registration this row configures. Scenario rows control per-event alert opt-in/out. The 'device_registration' value marks rows that store FCM token and platform for push delivery. | required |
enabled |
boolean |
Whether this notification scenario is active for the user. Mandatory scenarios (assignment_dispatch, security_alert) are always TRUE and cannot be set to FALSE by the user. NULL for device_registration rows where enabled is not applicable. | - |
threshold_days |
integer |
Coordinator-configurable delay in days before this scenario fires. For example, no_contact_reminder defaults to 10 days but a coordinator can adjust. NULL for scenarios that do not have a day-threshold trigger or for device_registration rows. | - |
fcm_token |
string |
Firebase Cloud Messaging device registration token used to deliver push messages to this specific device. Only populated on device_registration rows. Rotated by the mobile client on token refresh events. | - |
platform |
enum |
Mobile platform of the registered device. Required when fcm_token is present. Allows the backend to construct platform-specific APNs or FCM payloads. | - |
updated_at |
datetime |
Timestamp of the last modification to this setting record. Set by the database trigger on INSERT and UPDATE. Used to detect stale FCM tokens and apply TTL eviction. | required |
created_at |
datetime |
Timestamp when this configuration record was first created. Useful for auditing when a user registered a device or first configured a scenario preference. | required |
Database Indexes
idx_notification_setting_user_scenario
Columns: user_id, scenario_type
idx_notification_setting_user_id
Columns: user_id
idx_notification_setting_fcm_token
Columns: fcm_token
idx_notification_setting_scenario_enabled
Columns: scenario_type, enabled
Validation Rules
scenario_type_valid_enum
error
Validation failed
threshold_days_positive_integer
error
Validation failed
user_id_references_valid_user
error
Validation failed
fcm_token_format
error
Validation failed
platform_enum_valid
error
Validation failed
threshold_days_applicable_scenarios_only
warning
Validation failed
Business Rules
mandatory_scenarios_always_enabled
Rows where scenario_type is 'assignment_dispatch' or 'security_alert' must always have enabled = TRUE. These scenarios cannot be toggled off by any user role. Attempts to set enabled = FALSE for these types must be rejected with an error.
threshold_days_coordinator_only
The threshold_days field may only be modified by users with the Coordinator, Organization Administrator, or Global Administrator role. Peer Mentor role attempts to update threshold_days must be rejected. Only applicable to scenarios that have a threshold concept: no_contact_reminder, certification_expiry.
unique_user_scenario_combination
Each (user_id, scenario_type) pair must be unique. On first setup, seed rows are created for all scenario types for each user with sensible defaults. Duplicate inserts are handled via UPSERT (INSERT ... ON CONFLICT DO UPDATE).
fcm_token_requires_platform
If fcm_token is present, platform must also be set. A device registration row without a platform value is invalid and must be rejected. Enforced at both application and database constraint level.
seed_defaults_on_user_creation
When a new user account is created, the system must automatically insert notification_setting rows for all non-device scenario types using default values: enabled = TRUE for mandatory scenarios, enabled = TRUE for general_push, enabled = TRUE for no_contact_reminder with threshold_days = 10. This ensures every user has a complete preference profile from day one.
stale_fcm_token_eviction
FCM tokens with updated_at older than 60 days and no confirmed delivery should be flagged for eviction. The Push Notification Service deregisters and deletes stale device_registration rows after receiving delivery failure responses from the FCM server.
CRUD Operations
Storage Configuration
Entity Relationships
A user has multiple notification setting records — one per scenario type — controlling which alerts they receive