# CC Soccer D11 - Automated Notifications & Reminders

**Last Updated:** January 28, 2025  
**Status:** Specification in progress

---

## Overview

This document defines all automated notification scenarios that should be handled by cron jobs rather than manual admin actions. Each notification includes trigger conditions, target audience, timing, content, and configuration options.

---

## 1. Registration Reminders

### 1.1 Registration Closing Reminders

**Purpose:** Remind previous players to register before the deadline

**Trigger:** Cron job runs daily, checks upcoming registration close dates

**Target Audience:**
- Players who participated in previous N seasons (configurable)
- Exclude: Already registered for the upcoming season
- Exclude: Cancelled/expired registrations in lookback period

**Timing Options (Admin Configurable):**
- 4 weeks before registration closes
- 2 weeks before registration closes  
- 1 week before registration closes
- Default: All three enabled

**Content:**
```
Subject: [X weeks] until Fall 2025 Coed Registration Closes

Hi [First Name],

Registration for Fall 2025 Coed League closes in [X weeks] on [Date].

Don't miss out on your spot! Spaces are limited.

Register now: [Registration Link]

Questions? Contact us at [Board Email]

Thanks,
CC Soccer
```

**Configuration Needed:**
- Lookback period (how many seasons/years to include)
  - Default: 2 years
  - Options: 1 year, 2 years, 3 years, all time
- Which reminders to send (checkboxes)
  - [ ] 4 weeks before
  - [ ] 2 weeks before  
  - [ ] 1 week before
- Test mode (send to board only)

**Implementation Notes:**
- Query: Get all registrations from past N seasons
- Filter: Where user NOT in current season registrations
- Track: Store "notified_4wk", "notified_2wk", "notified_1wk" flags to avoid duplicates
- Cron frequency: Daily check

**Complexity:** HIGH (complex filtering, duplicate tracking, multiple timing windows)

---

## 2. Override Expiration Reminders

### 2.1 Override Expiring Soon

**Purpose:** Warn waitlist players their priority registration is about to expire

**Trigger:** Cron job runs daily, checks override expiration dates

**Target Audience:**
- Players with active overrides (`has_override = TRUE`)
- Where `override_expires` is between NOW and NOW+[X hours]

**Timing (Admin Configurable):**
- Default: 12 hours before expiration
- Options: 6 hours, 12 hours, 24 hours, 48 hours

**Content:**
```
Subject: Priority Registration Expires in [X hours] - Act Now!

Hi [First Name],

Your priority registration for [Season Name] expires in [X hours] at [Time] on [Date].

Register now before you lose your spot: [Registration Link]

If you don't register by the deadline, your spot will be offered to the next person on the waitlist.

Questions? Contact us at [Board Email]

Thanks,
CC Soccer
```

**Configuration Needed:**
- Warning window (how far in advance)
  - Default: 12 hours
  - Options: 6h, 12h, 24h, 48h
- Test mode (send to board only)

**Implementation Notes:**
- Query: Get registrations where `has_override = TRUE` and expiration within window
- Track: Flag "expiration_reminder_sent" to avoid duplicate reminders
- Cron frequency: Hourly or every 3 hours (depends on warning window)
- Edge case: What if override expires before cron runs? (acceptable - they still have the original notification)

**Complexity:** MEDIUM (straightforward query, simple logic)

---

## 3. [Future Notification Types - TO BE DEFINED]

### 3.1 Team Assignment Notification

**Status:** NOT AUTOMATED (currently manual via roster builder)

**Potential automation:**
- When: Roster builder is finalized (`roster_locked = TRUE`)
- Who: All registered players for that season
- Content: "Your team assignment is ready! You're on Team [X]"

**Decision:** Keep manual for now? Or automate?

---

### 3.2 Schedule Published Notification

**Status:** NOT AUTOMATED (currently manual)

**Potential automation:**
- When: Schedule is generated and published (`schedule_generated = TRUE`)
- Who: All registered players for that season
- Content: "Fall 2025 schedule is now available! View your games..."

**Decision:** Keep manual for now? Or automate?

---

### 3.3 Upcoming Game Reminders

**Status:** NOT DEFINED

**Potential feature:**
- When: 24 hours before game time
- Who: Players on both teams for that game
- Content: "Reminder: You have a game tomorrow at [Time] on [Field]"

**Decision:** Do we want this? Could be annoying (players know their schedule)

---

### 3.4 Credit Expiration Warning

**Status:** NOT DEFINED

**Potential feature:**
- When: 30 days before credit expires
- Who: Players with expiring credits
- Content: "You have $[Amount] in credits expiring on [Date]. Use them before they expire!"

**Decision:** Do we want this? Useful or too much?

---

### 3.5 Waitlist Position Updates

**Status:** NOT DOING (staying manual per requirements)

**Reasoning:** Board wants control over waitlist progression

---

## Configuration UI (Future Enhancement)

**Path:** `/admin/ccsoccer/settings/notifications`

**Settings Page Should Include:**

### Registration Reminders Section
- [ ] Enable registration closing reminders
- Lookback period: [Dropdown: 1 year, 2 years, 3 years, All time]
- Send reminders at:
  - [ ] 4 weeks before close
  - [ ] 2 weeks before close
  - [ ] 1 week before close
- [ ] Test mode (send to board email only)

### Override Reminders Section  
- [ ] Enable override expiration reminders
- Warning window: [Dropdown: 6 hours, 12 hours, 24 hours, 48 hours]
- [ ] Test mode (send to board email only)

### Other Notifications Section
- [ ] Send team assignment notifications when roster finalized
- [ ] Send schedule published notifications
- [ ] Send game day reminders (24 hours before)
- [ ] Send credit expiration warnings (30 days before)

### Global Settings
- Cron frequency: [Info display: "Every 3 hours via page load"]
- Last cron run: [Timestamp]
- [Button: Run Cron Now] (for testing)

---

## Implementation Strategy

### Phase 1: Core Infrastructure
1. Create cron hook that runs tasks
2. Create service: `AutomatedNotificationService`
3. Create configuration schema
4. Build logging/tracking system

### Phase 2: Registration Reminders (Priority 1)
1. Build query logic (previous players not registered)
2. Implement duplicate tracking (don't send twice)
3. Add configuration options
4. Test with poor man's cron

### Phase 3: Override Reminders (Priority 2)
1. Build query logic (expiring overrides)
2. Implement reminder sending
3. Add configuration options
4. Test timing

### Phase 4: Configuration UI (Priority 3)
1. Build admin settings form
2. Store config in database
3. Make services read from config
4. Add test mode functionality

### Phase 5: Additional Notifications (As Needed)
1. Evaluate actual user needs
2. Add based on feedback
3. Keep list in this document

---

## Cron Implementation Notes

**Using Poor Man's Cron:**
- Drupal's built-in cron runs on page loads
- Configure interval: Admin → Configuration → System → Cron
- Set to "Run cron every 3 hours"
- Timing is approximate (depends on site traffic)

**Cron Hook Pattern:**
```php
/**
 * Implements hook_cron().
 */
function ccsoccer_cron() {
  $notification_service = \Drupal::service('ccsoccer.automated_notifications');
  
  // Check registration reminders
  $notification_service->checkRegistrationReminders();
  
  // Check override expirations
  $notification_service->checkOverrideExpirations();
  
  // Log execution
  \Drupal::logger('ccsoccer')->info('Automated notification cron completed');
}
```

---

## Testing Strategy

**Development (DDEV):**
- All notifications go to MailHog
- Manual cron trigger: `ddev drush cron`
- Check MailHog: `ddev launch -m`

**Test Environment:**
- Use test mode (sends to board email only)
- Verify timing logic with edge cases
- Check duplicate prevention

**Production:**
- Start with test mode enabled
- Monitor first few runs
- Disable test mode when confident

---

## Questions to Answer

1. **Registration reminders:**
   - How far back to look? (1 year, 2 years, 3 years, all time?)
   - Should we exclude players who haven't played in X seasons? (inactive filter)
   - Send to email only, or SMS too?

2. **Override reminders:**
   - 12 hours is good? Or need more/less notice?
   - Email only or SMS too?

3. **Future notifications:**
   - Team assignment: Auto-send when roster locked?
   - Schedule published: Auto-send when generated?
   - Game reminders: Too annoying or helpful?
   - Credit expiration: Useful or noise?

4. **Configuration:**
   - Build UI now or hardcode initially?
   - Store in config or database?

---

## Success Metrics

**How we'll know it's working:**
- Fewer "I forgot to register" complaints
- Overrides don't expire unused
- Admin spends less time manually reminding people
- No duplicate notifications sent
- Notifications arrive within expected time windows

---

## Next Steps

- [ ] Complete this specification (answer outstanding questions)
- [ ] Review with Andrew
- [ ] Prioritize which notifications to build first
- [ ] Create implementation tasks in TODO.md
- [ ] Build Phase 1 (infrastructure)
- [ ] Build Phase 2 (registration reminders)
- [ ] Test and iterate

---

**Document Status:** 🚧 IN PROGRESS - Needs completion and review