---
phase: 05-web-push-notifications
plan: 06
subsystem: api/reminder-scheduler
tags: [web-push, reminder, node-cron, tdd, red-green, notif-01, shared-calendar]
dependency_graph:
  requires: [05-01, 05-02, 05-04]
  provides: [startReminderScheduler, runReminderCheck, shared-event 15-min reminder dispatch]
  affects:
    - apps/api/src/broker/reminderScheduler.ts
    - apps/api/src/index.ts
tech_stack:
  added: []
  patterns:
    - node-cron 1-min schedule (same shape as startBrokerPoller in poller.ts)
    - Drizzle cross-join (sql`1=1`) to fan shared events out to all push subscribers
    - in-memory dedup Set keyed uid:minuteBucket (D-12 single-process, no Redis)
    - per-event + per-subscription try/catch error isolation (T-05-18, T-05-19)
key_files:
  created:
    - apps/api/src/broker/reminderScheduler.ts
  modified:
    - apps/api/src/index.ts
decisions:
  - "Cross-join (sql`1=1`) used to pair each due shared event with ALL push subscriptions in one Drizzle query (2 innerJoins: calendarEvents→calendars→pushSubscriptions) — matches the test scaffold's mock chain shape"
  - "Grouping by uid after the flat cross-join result ensures all subscriptions for a deduped event are dispatched in one pass (prevents sub2 being silently skipped after dedup fires for sub1)"
  - "sentReminders.add(key) called BEFORE iterating subs to prevent re-entry on concurrent ticks"
  - "title fallback: event.title ?? uid — prevents 'undefined' in push copy for pre-05-07 rows"
metrics:
  duration: 6
  completed_date: "2026-06-10"
  tasks_completed: 1
  files_changed: 2
---

# Phase 05 Plan 06: reminderScheduler — shared timed 15-min reminder scan — Summary

TDD GREEN: `reminderScheduler.ts` implemented with D-05/D-07 SQL-enforced filtering, in-memory dedup, fan-out cross-join, and per-event error isolation — all 3 RED scaffold tests pass. Scheduler wired into `index.ts` `isMainModule()` guard.

## Tasks Executed

### Task 1: Implement reminderScheduler.ts (GREEN)

**Status:** Completed. Commit: `b95f671`

The RED scaffold (`tests/broker/reminderScheduler.test.ts`) was already committed in Plan 05-01 at `ef558b6`. This plan turns it GREEN.

Created `apps/api/src/broker/reminderScheduler.ts` with:

**`runReminderCheck(now = new Date())`** — single reminder scan cycle:
- Drizzle query: `db.select().from(calendarEvents).innerJoin(calendars, ...).innerJoin(pushSubscriptions, sql\`1=1\`)` — 2 innerJoins; cross-join fans each event out to all subscribers
- WHERE: `isShared=true AND allDay=false AND dtstartUtc >= now+14min AND dtstartUtc <= now+16min`
- D-05 enforced in QUERY (not copy) — personal events excluded at SQL level
- D-07 enforced in QUERY — all-day events excluded at SQL level
- Groups flat rows by uid, collects per-event subscription list
- Dedup: `sentReminders.add(\`${uid}:${minuteBucket}\`)` prevents window-boundary double-fire (T-05-18)
- Title fallback: `event.title ?? uid` — no "undefined" in reminder copy (NOTIF-01 / plan note)
- Notification payload: `{ title, body: 'Starts in 15 min', tag: \`reminder-${uid}\`, navigate: \`/calendar?date=${yyyyMmDd(dtstartUtc)}&event=${uid}\` }`
- Per-event and per-subscription try/catch for error isolation (T-05-18, T-05-19)
- Empty shared-calendar / empty push_subscriptions: cross-join returns 0 rows → zero sends, no crash (D-16)

**`startReminderScheduler()`** — node-cron `* * * * *` schedule (every minute):
- Same shape as `startBrokerPoller` in `poller.ts` — `.catch()` on the returned promise
- Not called at import time (guards the test process per WR-04)

**`index.ts`** — added `startReminderScheduler()` call in the `isMainModule()` guard, after `startOutboxWorker()` and after `webpush.setVapidDetails()` (so VAPID is configured before the scheduler starts).

**TDD Gate Compliance:**
- RED: `test(05-01): add Wave-0 RED scaffolds + VAPID fixture + setup truncation` — `ef558b6` (Plan 05-01)
- GREEN: `feat(05-06): implement reminderScheduler — shared timed 15-min reminder scan` — `b95f671`

## Verification

```
pnpm --filter @familysync/api exec vitest run tests/broker/reminderScheduler.test.ts

 Test Files  1 passed (1)
      Tests  3 passed (3)

grep -q "startReminderScheduler" apps/api/src/index.ts → PASSED
pnpm --filter @familysync/api typecheck → passed (no errors)
```

## Deviations from Plan

### Auto-fixed issues

None. Plan executed exactly as written.

### Architecture note (no deviation — design decision)

The cross-join approach (`innerJoin(pushSubscriptions, sql\`1=1\`)`) was chosen over two separate `db.select()` calls because:
1. The test scaffold's mock requires exactly 2 `innerJoin()` calls in a single chain (`.from().innerJoin().innerJoin().where()`)
2. A cross-join is semantically correct: shared reminder → all members
3. Grouping by uid after the flat result correctly handles the fan-out while maintaining the `uid:minuteBucket` dedup semantics

## Known Stubs

None. The scheduler is fully implemented. The `calendar_events.title` column may be NULL for events synced before Plan 05-07 (which adds title extraction to the sync path), but the null fallback (`event.title ?? uid`) handles this gracefully without stubbing.

## Threat Flags

No new threat surface. All three plan threats mitigated:

| Threat | Status |
|--------|--------|
| T-05-17: personal-calendar event in reminder | Mitigated — `WHERE isShared=true` enforced in SQL |
| T-05-18: duplicate reminder storm at window boundary | Mitigated — in-memory dedup Set; per-event try/catch |
| T-05-19: one bad subscription aborting cycle | Mitigated — per-subscription try/catch; dispatchPush swallows 410/404 |

## Self-Check

**Files created/verified:**
- [x] apps/api/src/broker/reminderScheduler.ts — exists

**Commits verified:**
- ef558b6: test(05-01): add Wave-0 RED scaffolds + VAPID fixture + setup truncation (RED gate — Plan 05-01)
- b95f671: feat(05-06): implement reminderScheduler — shared timed 15-min reminder scan (GREEN gate)

## Self-Check: PASSED