Push Notification Config
Data Entity
Description
Per-user device configuration for push notification delivery, including FCM or APNs device tokens, platform type, and per-category notification preference toggles. Enables granular user control over which notification types are delivered to which devices.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key generated server-side (gen_random_uuid()). Stable identifier for the device registration record. | PKrequiredunique |
user_id |
uuid |
Foreign key referencing users.id. Identifies the user who owns this device registration. | required |
device_token |
string |
FCM registration token (Android) or APNs device token (iOS). Issued by the platform push service and refreshed periodically by the OS. Must be treated as a credential — never logged in plaintext. | requiredunique |
platform |
enum |
The mobile platform this device token belongs to, determining whether delivery uses FCM (android) or APNs (ios). | required |
category_preferences |
json |
Map of notification category keys to boolean enabled/disabled flags. Categories correspond to defined scenario types: assignments, activity_reminders, certificate_expiry, impact_summaries, achievement_badges, coordinator_alerts, reimbursement_status, calendar_sync, system_announcements. A missing key is treated as enabled (opt-out model). Structure: { 'assignments': true, 'certificate_expiry': true, ... } | - |
is_active |
boolean |
Whether this device token is currently valid and should receive push notifications. Set to false when the token is reported invalid by FCM/APNs delivery failure, or when the user logs out from this device. | required |
app_version |
string |
Semantic version string of the app build that registered this token (e.g. '2.1.0'). Used to identify stale registrations from outdated builds and for debugging delivery issues. | - |
device_name |
string |
Human-readable device label as reported by the OS (e.g. 'iPhone 15 Pro', 'Pixel 8'). Displayed in notification settings to help users identify which device a configuration belongs to. | - |
token_refreshed_at |
datetime |
UTC timestamp of the most recent token refresh. Tokens older than 60 days without refresh are flagged as potentially stale and eligible for cleanup. | - |
created_at |
datetime |
UTC timestamp when this device registration was first created, set server-side on insert. | required |
updated_at |
datetime |
UTC timestamp of the most recent mutation to this record, maintained by a Supabase database trigger. Used for cache invalidation and audit purposes. | required |
Database Indexes
idx_push_notification_configs_user_id
Columns: user_id
idx_push_notification_configs_device_token
Columns: device_token
idx_push_notification_configs_user_active
Columns: user_id, is_active
idx_push_notification_configs_platform
Columns: platform
idx_push_notification_configs_token_refreshed_at
Columns: token_refreshed_at
Validation Rules
device_token_non_empty
error
Validation failed
device_token_max_length
error
Validation failed
platform_enum_constraint
error
Validation failed
user_id_references_valid_user
error
Validation failed
category_preferences_valid_json
error
Validation failed
category_preferences_value_types
error
Validation failed
app_version_format
warning
Validation failed
unique_device_token_on_upsert
warning
Validation failed
Business Rules
one_config_per_device_token
Each physical device token must be globally unique across all users. If a device token is re-registered (e.g. after app reinstall or user switch), the existing record for that token must be updated rather than creating a duplicate.
multi_device_allowed_per_user
A single user may have push notification configs registered across multiple devices simultaneously (e.g. a personal phone and a tablet). All active device configs must receive notifications matching the user's preferences unless per-device category overrides differ.
deactivate_on_token_failure
When the Push Notification Gateway receives a delivery failure response indicating an invalid or unregistered token (FCM error code NotRegistered, APNs 410 status), the corresponding push_notification_configs record must be marked is_active = false immediately to prevent repeated failed delivery attempts.
deactivate_on_logout
When a user signs out from a specific device, the push_notification_configs record for that device's token must be set to is_active = false. If the logout is a full account wipe, all configs for that user may be deactivated.
upsert_on_token_refresh
FCM and APNs periodically issue new device tokens to replace old ones. When push-notification-service detects a new token on app launch, it must upsert the push_notification_configs record — updating device_token and token_refreshed_at for the existing row identified by (user_id, platform, device_name) rather than inserting a duplicate.
category_opt_out_model
Notification categories not present in category_preferences are treated as enabled by default (opt-out model). Disabling a category requires an explicit false entry. This ensures newly introduced notification categories are delivered to all users without requiring a migration.
rls_user_scope
Supabase RLS policies must restrict read and write access to push_notification_configs rows to the owning user (auth.uid() = user_id) and backend service roles only. Mobile clients must never be able to read or modify another user's device tokens.
stale_token_cleanup
Records where token_refreshed_at is older than 60 days and is_active = false are eligible for deletion during periodic maintenance. This prevents unbounded table growth from abandoned device registrations.
CRUD Operations
Storage Configuration
Entity Relationships
A user may have push notification configurations registered across multiple devices