feat: Enhance event and notification systems with comprehensive reminder workflows and documentation

rsmithlal · rsmithlal · commit 71b9e473e5f8 · 2025-08-21T18:31:53.000-02:30
diff --git a/docs/events_flow.mmd b/docs/events_flow.mmd
@@ -17,8 +17,39 @@ flowchart TD
   SCOPE -->|>= now| UPCOMING[Upcoming]
   SCOPE -->|< now| PAST[Past]
 
-  %% Optional Geocoding
+  %% Optional Geocoding & Location
   SAVE --> GEO[Optional: geocoding job]
+  SAVE --> LOC[LocatableLocation\npolymorphic]
+
+  %% Event Notification System
+  SAVE --> SCHED[EventReminderSchedulerJob]
+  SCHED --> CALC{Calculate reminder times}
+  CALC --> R24[Schedule 24h reminder]
+  CALC --> R1[Schedule 1h reminder]
+  CALC --> RS[Schedule start reminder]
+  
+  %% Background Reminder Jobs
+  R24 --> RJ24[EventReminderJob\n24 hours before]
+  R1 --> RJ1[EventReminderJob\n1 hour before]
+  RS --> RJS[EventReminderJob\nat start time]
+  
+  %% Reminder Processing
+  RJ24 --> PROC[Process attendees]
+  RJ1 --> PROC
+  RJS --> PROC
+  PROC --> GOING{Filter 'going' status}
+  GOING --> ERN[EventReminderNotifier]
+  
+  %% Multi-channel delivery
+  ERN --> AC[Action Cable\nReal-time notification]
+  ERN --> EMAIL{Email enabled?}
+  EMAIL -->|Yes| MAIL[EventMailer\n15min delay]
+  EMAIL -->|No| SKIP[Skip email]
+  
+  %% Event Updates
+  UPDATE[Event updated] --> EUN[EventUpdateNotifier]
+  EUN --> AC
+  EUN --> EMAIL
 
   %% Display & Actions
   PZ --> SHOW[Show page]
@@ -31,16 +62,23 @@ flowchart TD
   AUTH -->|Yes| RSVP[RSVP Actions]
   AUTH -->|No| GUEST[Guest view only]
   RSVP --> INT[Mark Interested]
-  RSVP --> GOING[Mark Going]
+  RSVP --> GOING_ACT[Mark Going]
   RSVP --> CANCEL[Cancel RSVP]
   INT --> ATT[EventAttendance record]
-  GOING --> ATT
+  GOING_ACT --> ATT
   CANCEL --> DEL[Delete attendance]
   
+  %% Trigger reminders when status changes
+  ATT --> RESCHED[Reschedule reminders\nif going]
+  
   %% ICS Export
   SHOW --> ICS[ICS Export]
   ICS --> ICSAUTH{Authorization check}
   ICSAUTH -->|Public or authorized| EXPORT[Generate .ics file]
   ICSAUTH -->|Not authorized| 404[404 Not Found]
   EXPORT --> CAL[Calendar application]
 
+  %% Notification preferences
+  ERN -.-> PREFS[Check user preferences:\nevent_reminders, notify_by_email]
+  EUN -.-> PREFS
+
diff --git a/docs/events_flow.png b/docs/events_flow.png
diff --git a/docs/events_system.md b/docs/events_system.md
@@ -1,19 +1,144 @@
 # Events & Calendars
 
-This## What's Implemented
+This document explains the Event model, how events are created and displayed, how visibility works, how calendars fit in, and the comprehensive notification system for event reminders and updates.
+
+## What's Implemented
 - **RSVPs/Attendees**: `EventAttendance` model with `person_id`, `event_id`, `status` (interested/going/not_going), guarded by privacy/policy.
 - **ICS Export**: Export endpoint at `/events/:id/ics` that renders VEVENT from name/description/time/location.
+- **Event Reminder System**: Comprehensive notification system for upcoming events with multiple delivery channels.
+- **Event Update Notifications**: Automatic notifications when event details change.
+- **Location Support**: Full location support with polymorphic `LocatableLocation` model.
 
 ## What's Not Implemented Yet
 - **Recurrence**: No repeat rules; all events are single instances.
 - **Calendar Entries**: `CalendarEntry` exists but is not used to associate events to calendars.
-- **Event Location/Address**: Address association is commented out; no geocoding integration active.
 - **Advanced RSVP Features**: No waitlists, capacity limits, or guest allowances.
-- **Event Reminders**: No notification system for upcoming events.
-- **Event Updates/Changes**: No notification system when event details change.
-- **Bulk Operations**: No bulk event creation, editing, or management tools.e explains the Event model, how events are created and displayed, how visibility works, and how calendars fit in. It also notes what is not yet implemented (RSVPs, attendees, recurrence) so maintainers know the current scope.
+- **Bulk Operations**: No bulk event creation, editing, or management tools.
 
 ## Event Attendance & RSVPs
+
+## Event Reminder & Notification System
+
+### Components Overview
+The event notification system consists of several integrated components:
+
+- **EventReminderNotifier**: Noticed event class for sending event reminder notifications
+- **EventReminderJob**: Background job for processing reminder notifications for all attendees
+- **EventReminderSchedulerJob**: Schedules future reminder notifications at appropriate intervals
+- **EventMailer**: Handles email delivery for event reminders and updates
+- **EventUpdateNotifier**: Sends notifications when event details change
+
+### Event Reminder Workflow
+
+#### Scheduling Reminders
+1. When an event is created or updated, `EventReminderSchedulerJob` is triggered
+2. The scheduler calculates appropriate reminder times based on event start time:
+   - **24 hours before**: For events more than 24 hours away
+   - **1 hour before**: For events more than 1 hour away
+   - **At start time**: For immediate notifications
+3. Background jobs are scheduled using `perform_at` for each reminder interval
+4. Only "going" attendees receive reminder notifications
+
+#### Notification Delivery
+1. `EventReminderJob` processes each scheduled reminder:
+   - Finds all attendees with "going" status
+   - Creates `EventReminderNotifier` instances for each attendee
+   - Respects user notification preferences
+2. `EventReminderNotifier` handles multi-channel delivery:
+   - **Action Cable**: Real-time in-app notifications via `NotificationsChannel`
+   - **Email**: HTML emails with event details (15-minute delay to batch notifications)
+3. Email delivery is conditional based on:
+   - User has email address configured
+   - User has `notify_by_email` preference enabled
+   - User has `event_reminders` preference enabled
+   - Anti-spam: Only one email per unread event notifications
+
+#### Event Update Notifications
+1. When event details change, `EventUpdateNotifier` is triggered
+2. Sends notifications to all attendees about the changes
+3. Includes information about what specific attributes changed
+4. Uses the same delivery channels as reminder notifications
+
+### Notification Preferences
+Users can control event notifications through their preferences:
+- `event_reminders`: Enable/disable event reminder notifications
+- `notify_by_email`: Enable/disable email notifications globally
+- `show_conversation_details`: Control visibility of conversation details in emails
+
+### Anti-Spam & Batching
+- **Email Batching**: 15-minute delay on email delivery to group related notifications
+- **Duplicate Prevention**: Only one email per unread notification group per event
+- **Preference Respect**: All notifications respect user preferences and can be disabled
+
+### Technical Implementation Details
+
+#### Classes & Responsibilities
+- **`BetterTogether::EventReminderNotifier`**: Noticed event class extending `ApplicationNotifier`
+  - Handles multi-channel delivery (Action Cable + Email)
+  - Includes anti-spam logic and preference checking
+  - Generates localized notification content
+- **`BetterTogether::EventReminderJob`**: Background job extending `ApplicationJob`
+  - Processes events and finds "going" attendees
+  - Creates notifier instances for each attendee
+  - Handles error cases gracefully (missing events, connection issues)
+  - Queue: `:notifications` with retry configuration
+- **`BetterTogether::EventReminderSchedulerJob`**: Scheduling job
+  - Calculates appropriate reminder intervals based on event timing
+  - Schedules future `EventReminderJob` instances
+  - Prevents scheduling reminders for past events or drafts
+- **`BetterTogether::EventMailer`**: Mailer class extending `ApplicationMailer`
+  - Renders HTML emails with event details
+  - Uses Rails 7+ parameter pattern (`params[:key]`)
+  - Includes event location, timing, and registration information
+- **`BetterTogether::EventUpdateNotifier`**: Handles event change notifications
+  - Triggers when event attributes are modified
+  - Notifies all attendees (not just "going" status)
+  - Includes information about what changed
+
+#### Notification Timing Strategy
+- **24-hour reminders**: For events starting more than 24 hours in the future
+- **1-hour reminders**: For events starting more than 1 hour in the future
+- **Start-time notifications**: For events starting within the hour
+- **Update notifications**: Immediate when event details change
+
+#### Queue & Background Processing
+- Uses `:notifications` queue for all event-related jobs
+- Retry configuration: Up to 5 attempts with polynomial backoff
+- Discard policy: `ActiveRecord::RecordNotFound` errors are discarded
+- Error handling: Jobs complete gracefully for missing/invalid events
+
+### Models & Data Flow
+- **Event**: Has many `event_attendances` and `attendees` (people)
+- **EventAttendance**: Links person to event with status (interested/going/not_going)
+- **Noticed::Notification**: Stores notification records with read/unread status
+- **Noticed::Event**: Base class for all notifier events
+
+### Testing Coverage
+The event reminder system has comprehensive test coverage:
+
+#### EventReminderNotifier Specs
+- Tests notification content generation (title, body, identifiers)
+- Validates parameter handling and defaults
+- Verifies unread count inclusion in messages
+- Uses mock objects following established patterns
+
+#### EventReminderJob Specs  
+- Tests attendee filtering and notification delivery
+- Validates error handling for missing/invalid events
+- Confirms queue configuration and retry policies
+- Verifies reminder type parameter handling
+
+#### EventMailer Specs
+- Tests email rendering with event details
+- Validates headers, subject lines, and recipient handling
+- Tests localization support
+- Confirms delivery methods work correctly
+
+#### Integration Testing
+- Tests complete notification workflow from event creation to delivery
+- Validates preference-based filtering
+- Tests anti-spam and batching behavior
+- Ensures proper authorization checks
 - Model: `BetterTogether::EventAttendance`
 - Associations: `belongs_to :event`, `belongs_to :person`
 - Status enum: `interested`, `going`, `not_going`
diff --git a/docs/notifications_flow.mmd b/docs/notifications_flow.mmd
@@ -16,6 +16,21 @@ flowchart TD
     MREAD[View conversation] --> MR[Mark read via NotificationReadable]
   end
 
+  %% Events Flow
+  subgraph EVT[Events]
+    E1[Event created/updated] --> ERS[EventReminderSchedulerJob]
+    ERS --> ERJ[EventReminderJob\nscheduled at intervals]
+    ERJ --> ERN[EventReminderNotifier]
+    E2[Event details changed] --> EUN[EventUpdateNotifier]
+    ERN -->|deliver to going attendees| EV
+    EUN -->|deliver to all attendees| EV
+    EM -. gated .-> ERN
+    EM -. gated .-> EUN
+    ERN -.-> ERN_NOTE[Email waits 15m; one email per unread event\nRespects: event_reminders, notify_by_email]
+    EUN -.-> EUN_NOTE[Includes changed attributes info]
+    EREAD[View event] --> ER[Mark read via NotificationReadable]
+  end
+
   %% Exchange: Matches
   subgraph MAT[Exchange Matches]
     X1[Offer/Request created] --> MF[Exchange#notify_matches]
diff --git a/docs/notifications_flow.png b/docs/notifications_flow.png
diff --git a/docs/notifications_system.md b/docs/notifications_system.md
@@ -38,6 +38,15 @@ This document explains how notifications are produced, delivered, deduplicated,
 
 - PageAuthorshipNotifier (`app/notifiers/better_together/page_authorship_notifier.rb`)
   - Trigger: author added/removed on a Page (via `BetterTogether::Authorship`).
+  - Recipients: all current page authors.
+  - Delivery: Action Cable immediately; Email deferred (`wait 15.minutes`) and only if `send_email_notification?`.
+  - Email dedupe grouping: one email per unread page per recipient (on-site notifications may still accumulate).
+
+- EventReminderNotifier (`app/events/better_together/event_reminder_notifier.rb`)
+  - Trigger: `EventReminderJob` execution 1 hour before event start time (scheduled by `EventReminderSchedulerJob`).
+  - Recipients: Event creator and interested community members.
+  - Delivery: Action Cable immediately; Email deferred and only if `send_email_notification?`.
+  - Email content: Localized event details, start time, location, and community context.
   - Delivery: Action Cable immediately; Email deferred (`wait 15.minutes`) and only if `send_email_notification?`.
   - Email dedupe grouping: one email per unread page per recipient (on-site notifications may still accumulate).
 
@@ -50,11 +59,57 @@ This document explains how notifications are produced, delivered, deduplicated,
 - Usage:
   - Joatu controllers include the concern and mark `MatchNotifier` read on Offer/Request show; mark Agreement-related notifications read on Agreement show.
   - ConversationsController uses the concern to mark `NewMessageNotifier` notifications read when viewing a conversation with messages.
+  - EventsController uses the concern to mark `EventReminderNotifier` notifications read when viewing event details.
   - NotificationsController uses the concern for record-based marking.
 
+## Event Notifications
+
+### EventReminderNotifier
+- Notifier Class: `BetterTogether::EventReminderNotifier` (Noticed event in `app/events/better_together/event_reminder_notifier.rb`)
+- Purpose: Send event reminders to interested participants
+- Trigger: `EventReminderJob` executes 1 hour before event start_time for events with notifications enabled
+- Recipients: Event creator and any interested members (those who've shown interest in the event)
+- Record: BetterTogether::Event being reminded about
+- Params: `{ event: <Event instance>, host_community: <Community instance> }`
+
+### Event Email System
+- Mailer: EventMailer (`app/mailers/better_together/event_mailer.rb`)
+- Template: `event_reminder.html.erb` (I18n localized subject and body)
+- Email Logic:
+  - Check `recipient.send_email_notification?` preference
+  - Use recipient's preferred locale for rendering
+  - Subject/body from I18n keys: `better_together.event_mailer.event_reminder.subject`/`.body`
+  - Include event title, start time (localized), location, and community context
+  - Handle unread notification count in message
+- Delivery: Action Cable immediately; Email deferred and only if email notifications enabled
+- Email batching: Multiple events can trigger separate notifications (no artificial grouping)
+
+### Event Reminder Scheduling
+- Background Job: `EventReminderSchedulerJob` (runs periodically via cron/scheduler)
+- Purpose: Schedule `EventReminderJob` instances for upcoming events
+- Logic: Query events with notifications enabled that start in ~1 hour, schedule individual reminder jobs
+- Queue: `:notifications` with retry configuration
+- Error Handling: Individual event reminder failures don't affect batch processing
+
+### Event Notification Integration
+- Triggers: 
+  - Event creation with notifications enabled: schedule future reminder
+  - Event update: reschedule reminder if start_time changes
+  - Event deletion: cancel pending reminder jobs
+- Action Cable: Real-time notifications via `BetterTogether::NotificationsChannel`
+- Read Marking: Event-specific notifications marked read when viewing event details
+
+### Event Anti-Spam Measures
+- One reminder per event per recipient (no duplicate scheduling)
+- Only events with explicitly enabled notifications trigger reminders
+- Respects user email preferences (`send_email_notification?`)
+- Failed reminders logged but don't retry indefinitely
+- Reminder scheduling only occurs for future events (past events ignored)
+
 ## Recipient Preferences & Email
 
 - Email delivery is gated:
+  - EventReminderNotifier: `recipient.send_email_notification?` must be true for email delivery
   - NewMessageNotifier and PageAuthorshipNotifier: `recipient.notify_by_email` must be true, and an internal `should_send_email?` ensures one email per unread conversation/page.
   - AgreementNotifier and AgreementStatusNotifier: `recipient.notification_preferences['notify_by_email']` (and presence of email) must be true.
   - MatchNotifier: `recipient_has_email?` checks email and preferences.
@@ -68,6 +123,8 @@ This document explains how notifications are produced, delivered, deduplicated,
 ## Known Behaviors / Considerations
 
 - NewMessage/PageAuthorship email dedupe does not dedupe on-site notifications; MatchNotifier dedupes on-site notifications as well (preventing duplicate unread for the pair).
+- EventReminderNotifier sends one notification per event per recipient; scheduling prevents duplicate reminders for the same event.
+- Event reminders are only sent for events with notifications explicitly enabled and future start times.
 - Unread count included in Action Cable payload is computed per-recipient at send time.
 - JSONB params store reference GlobalIDs for Offer/Request; read markers account for both direct string and ActiveJob `_aj_globalid` formats.
 
@@ -76,4 +133,5 @@ This document explains how notifications are produced, delivered, deduplicated,
 - Consider adding on-site dedupe/grouping to NewMessage/PageAuthorship similar to MatchNotifier if desired.
 - Aggregate match notifications when many pairs are found at once.
 - Add per-notifier throttling windows (e.g., rate limit bursty events via job scheduling).
+- Event reminders could be enhanced with configurable timing (currently fixed at 1 hour before).
 
