Scheduled Notifications Flow

Flow Overview

These diagrams outline the process for creating scheduled notifications based on user intentions and subsequently sending them out.

1. Notification Creation/Scheduling Flow

2. Notification Sending Flow

Process Description

1. Notification Creation/Scheduling:

   • This process is typically triggered when a user updates their profile or, more significantly, changes their selected Intention(s). The IntentionScheduledNotificationsService::createUserScheduledNotifications method is called.
   • The service first checks if the necessary user profile and notification settings exist (checkRequirements). If settings are missing, default ones might be created via UserService.
   • If requirements are met, the service dispatches a batch of jobs to the high priority queue. Depending on the $type parameter passed to the service, it might dispatch jobs for 'all' notification types or just a specific one.
   • The dispatched jobs (CreateUserAffirmationsJob, CreateUserLettersJob, etc.) are responsible for the actual creation logic for their respective content types:
     • Each job likely fetches the relevant content items (e.g., Affirmations associated with the user's intention).
     • It retrieves the user's notification settings (start/end time, frequency) to determine appropriate times.
     • It calculates specific future date_time values for each notification to be scheduled.
     • It creates records in the scheduled_notifications table, linking the user_id, the content (messageable_id, messageable_type), the calculated date_time, and potentially the related intention_id.

2. Notification Sending:

   • The HandleIntentionScheduledNotificationsJob is configured to run every five minutes through Laravel's Task Scheduling in bootstrap/app.php, where it's registered with $schedule->job(new HandleIntentionScheduledNotificationsJob())->everyFiveMinutes();.
   • This central job acts as a dispatcher. It immediately dispatches the ProcessAffirmationScheduledNotificationsJob and then subsequently dispatches the jobs for other notification types (ProcessLetter..., ProcessAudioAffirmation..., etc.) with increasing delays (40s, 80s, 120s, 160s). This staggering prevents sending all notification types at the exact same moment.
   • Each individual Process...Job (e.g., ProcessAffirmationScheduledNotificationsJob) executes the sending logic for its type:
     • It queries the scheduled_notifications table for records of its specific type that are due to be sent (likely checking if date_time is in the past and last_sent_at is null or older than a certain threshold, although the exact query logic isn't shown).
     • For each due notification found, it retrieves the user and the associated content (messageable).
     • It calls Firebase Cloud Messaging (FCM) to deliver the push notification content to the user's device.
     • Upon successful sending (or attempted sending), it updates the last_sent_at timestamp on the corresponding scheduled_notifications record to prevent it from being sent again immediately. Note: The IntentionScheduledNotificationsService::updateLastSentTime method exists but its usage isn't shown directly in the provided job code; the Process...Jobs likely update last_sent_at directly.

Key Models & Services

• IntentionScheduledNotificationsService: Service responsible for initiating the creation of scheduled notifications based on user profile/intentions.
• HandleIntentionScheduledNotificationsJob: Central job triggered by the scheduler to dispatch individual sending jobs with delays.
• CreateUser[Type]Job (e.g., CreateUserAffirmationsJob): Jobs responsible for querying content and creating ScheduledNotification records in the database.
• Process[Type]ScheduledNotificationsJob (e.g., ProcessAffirmationScheduledNotificationsJob): Jobs responsible for querying due notifications, triggering the actual sending, and updating the last_sent_at status.
• ScheduledNotification: Eloquent model representing a single scheduled notification entry in the database, linking user, content, and time.
• User: The recipient of the notification.
• Intention: May be linked to a notification.
• [Content Models] (Affirmation, Letter, etc.): The actual content associated with a notification via the messageable relationship.
• (Implicit) System Scheduler: Cron or Laravel Scheduler that runs HandleIntentionScheduledNotificationsJob periodically.
• (Implicit) Notification Sending Service: The service used to send push notifications (e.g., FCM) or other notification types.
• (Implicit) Queue System: Laravel's queue system manages the execution of dispatched jobs.