Skip to content
View in Notion

Notifications & Actions ​

Feature Overview ​

Notifications serve two purposes in PPP:

  1. Transactional — event-driven alerts (WBA submitted, timesheet ready to review, reviewer feedback received)
  2. Proactive / nudge — scheduled prompts that drive engagement when users fall behind or haven't completed a task (CPD deficit, plan not submitted, timesheet incomplete, profile gaps)

The notification bell in the header surfaces both types. The Action Items page (previously called "Inbox" — renamed 25 Mar 2026, #3953; renamed to "Task Manager" by #11767; renamed back to "Action Items" per Matt's #12234 confirmation, #12326) aggregates all outstanding action items into a unified work queue. This spec's own naming callout is retained for history; action-items.md is the current naming and behaviour owner (see "This spec supersedes notifications.md" there).

Naming — The page/nav item must be called "Action Items" (previously "Task Manager", #11767, superseded by #12326; before that "Actions"/"Action Items", before that "Inbox", #3953). Never "Inbox" — it creates a mental association with email that confuses users. The /action-items route path itself is unchanged throughout these renames to preserve existing bookmarks/redirects.

Original Vision ​

Unified To-Do List (Jan 2026) ​

From walk-through notes and March 2026 call:

"All outstanding items surfaced as action items — not just WBA, but also CPD deficit, missing profile fields, incomplete timesheets" "Drive users back to the notification bell — this is the single entry point for all reminders"

Every proactive nudge and outstanding item should surface as a badge/entry in the notification bell's To-Do tab, not as a separate UI element.

Proactive Prompt Engine ​

Scheduled evaluations that fire contextual prompts:

TriggerConditionAction
CPD deficitUser behind target hoursPush + in-app: "You need X more CPD hours"
CPD plan not submittedPlan overduePersistent reminder until submitted
Timesheet incompleteEnd of shift / fortnightPush: "Complete your timesheet"
Profile gapsMissing CV / immunizations / supervisorIn-app prompt until resolved
Wellness questionnaireWeekly cadencePush reminder

Notification Bell → To-Do Tab ​

  • Bell icon in header with badge count (unread items)
  • Two sub-tabs: Notifications (event feed) and To-Do (action items)
  • To-Do items have status tracking (pending / in-progress / done)
  • Progress ring in To-Do tab shows overall completion
  • Daily digest push notification summarising outstanding items (#3702)

Push Notifications (Mobile) ​

  • Native push via Expo for mobile
  • All in-app notifications also fire as push notifications (#3610)
  • Users directed back to bell for all reminder types (#3611)

Open Questions ​

No open questions are owned by this spec as of 2026-10-03. The one follow-up, whether an admin can change where each notification lands (To-do, Notifications or both), was action-items.md Q9, closed 2026-10-05 (editable, built in #12764). It is a column on the admin Notification schedule described in notifications.admin.trigger-catalogue.

Closed Questions (3) — click to expand
#QuestionSourceAnswer
Q2 (was OQ-N1)Push on/off option. On 2026-03-24 you said of native mobile notifications: "I want them to have the option for that". Today the phone's own permission prompt is the only on/off switch for push, and the Settings tab lets users opt out per category (Q1 below). Is that enough, or do you want a separate in-app "push notifications on/off" switch?transcript-2026-03-24 ~00:27:24Closed 2026-10-03 (inferred from existing evidence, Rob approved): no separate push master switch. In context, Matt's "option" was native phone notifications as well as in-app ones. Rob asked "do you want the notifications that are native to the mobile app", and Matt said "I want them to have the option for that".† That is built: native push (#3610), the phone's own permission prompt, the per-category opt-outs (Q1) and the geofence push switch (GeoFencePreferences.tsx). Matt has not asked for a master switch since. No AC change.
Q3 (was OQ-N2)Admin trigger console: what "over 1 year" means. Your Task 16 brief asks for an "admin console of all notification triggers over 1 year - occasion, recurrence etc". Should this be (a) a list of every trigger with its occasion and recurrence, (b) a 12-month calendar showing when each scheduled reminder will fire, or (c) both? Should it show which users (consultant / non-consultant) each one goes to?issue-11218 (2026-07-29); notion-admin-console (2026-08-04)Closed 2026-10-03 (audience answered by Matt, shape inferred; Rob approved): an editable Notification schedule table, not a calendar. Matt's ADMIN CONSOLE page asks for a "Notification schedule" with the "ability to select type of users involved in notification (or specific user); timing ; words of notification; linked action/where it takes user once notification clicked".† So each row is one trigger, with its audience (user type or a specific user), timing and recurrence ("occasion, recurrence etc", #11218), wording and click-through. Admins can edit it. No 12-month calendar view. notifications.admin.trigger-catalogue is updated to match.
Q4 (was OQ-N3)Notification vs to-do: the rule. On 2026-09-01 you said "we need to delineate I guess what is an action item and what is a notification. So we probably need to have a … metric for that." The working rule so far (2026-05-26, 2026-06-03) is: a notification tells you something happened; a to-do is something you must act on. Is that the rule? Should any event that needs action raise both (e.g. "feedback has arrived" → notification + to-do)?transcript-2026-09-01 ~00:29:59; transcript-2026-05-26 ~01:15:06; transcript-2026-06-03 ~00:07:43; issue-12234 (2026-09-20); notion-action-items-briefClosed 2026-10-03 (answered by Matt across 2026-05-26 to 2026-09-20; Rob approved). A to-do is something this user must act on. A notification tells the user something happened, or that a third party completed something. One event can raise both. To-dos are reached from the logo control and notifications from the bell. Matt, 2026-09-20: Action Items is "to do specifically" and "Notifications still come up in the bell".†† notifications.delineation.notification-vs-todo is now settled.
  • Q1 (#4979) — Resolved 5 May (engineering-led, Matt to ratify): opt-out matrix below. Transactional (event-driven) notifications stay mandatory because they carry user-actionable obligations (sign-offs, verifications). Proactive nudges + Platform Reminders are opt-out per category. Email channel is independently togglable from in-app channel.

    CategoryChannelUser can disable?Default
    WBA / appraisal verification request receivedIn-app + emailNoOn
    Document verified / rejectedIn-app + emailNoOn
    CPD activity awaiting approval (you're approver)In-app + emailNoOn
    CPD deficit nudgeIn-app + pushYesOn
    CPD plan not submitted nudgeIn-app + pushYesOn
    Timesheet incompleteIn-app + pushYesOn
    Wellness questionnaire weekly cadencePushYesOn
    Profile completion nudgesIn-appYesOn
    Registration / immunisation / training expiryIn-app + emailNo (compliance)On
    Platform announcements / product updatesEmailYesOn
    Marketing (upgrade / cross-sell)EmailYesOff

Acceptance Criteria ​

Notification Bell & Feed ​

  • ✅ Bell icon in header with unread badge count
  • ✅ Badge count reflects all unread notifications, not only first page (#4974)
  • ✅ Event-driven notifications: WBA, feedback, reflection, timesheet approval
  • ✅ All notification types deep-link to the correct record (#3549, #3575–3580)
  • ✅ Roadmap milestone and passport expiry reminders deep-link correctly (#4975); the PPP Passport indemnity, indemnity-expired and training expiry reminders (#12810) deep-link to /ppp-passport too (#12896)
  • ✅ Wellness reminder type routes to wellness questionnaire (#4976)
  • ✅ Timesheet approved/rejected/forwarded deep-link to batch (#4978)
  • ✅ 360 supervisor review shows Action chip and work-queue link (#4977)
  • ✅ WBA assessor receives email when external/unregistered (#5026)
  • ✅ Mark-all-as-read uses a single server-side endpoint, not N PATCH calls (#4980), and marks every unread notification of the caller read — not only the rows the client has loaded (#12564)
  • ✅ Bell drives users back to all reminder types (#3611)
  • ✅ Mobile: notification bell in correct header position (#3972)
  • ✅ "View all notifications" navigates directly to /action-items?tab=notifications without a redirect hop (#8942)
  • ✅ Bell-open and per-row click are semantically decoupled: opening the bell sets seenAt (clears the red pill) without touching isRead (blue row bars persist until each row is explicitly clicked) (#8978)
  • ✅ Badge count driven by seenAt IS NULL (never-opened count); isRead/readAt remains the per-row read flag (#8978)
  • ✅ System-generated notifications (scheduled reminders and automated prompts) render "PPP System" as their sender, never a person. The decision is made on the notification type, not on sender_id — sender_id is unreliable in both directions: historical rows written before #11316 recorded the recipient as their own sender, and until #12542 createNotification defaulted senderId from ctx.identity.email whenever the caller passed a falsy value, so any automated notification raised on a request from the user's own device (e.g. geofence_exit) self-sendered on the then-current code path (#11313). createNotification now applies a three-way rule (#12542): a number is used as-is; undefined (the caller did not say) falls back to the acting user from ctx.identity; an explicit null stays anonymous and createdBy stays unset. Self-sendering therefore persists only in historical rows and for producers that omit senderId entirely — the five producers that pass null (supportView.ts, cpdReminderSettings.ts, resolveSpeciality.ts, geoFenceNotification.ts, wellnessService/notification) now store no sender. The client-callable notifications.create never honours a client-supplied senderId/createdBy (the caller is always the sender) and rejects system-generated and mandatory types with BAD_REQUEST; notifications.list joins only the sender's id, firstName and lastName, never the full users row; and migration 0253 clears sender_id/created_by from support_view_accessed rows written before the fix
  • ✅ Every scheduler-raised notification type is enumerated in SYSTEM_GENERATED_NOTIF_TYPES. The system-sender rule above is an allowlist keyed on type, so a type the scheduler raises but the list omits silently falls through to the sender_id-null role-label fallback and renders a human role (e.g. "Consultant") as the sender of an automated message. Adding a new scheduled notification type therefore requires adding it to that list in the same change. Found live on UAT during the #11218 walkthrough: cpd_provider_unverified_followup, raised by processCpdProviderVerificationReminders, rendered as "Consultant" on 14 of the seeded account's 17 notifications (#11218)
  • ✅ notifications.bell.heads-up-dropdown — notifications keep coming up in the header bell, and they stay separate from the Action Items to-do list. Clicking the bell opens a drop-down over the current screen with the latest five notifications, like a heads-up display. It does not navigate away. Clicking a row takes the user to that record. "View all notifications" goes to the Notifications part of Action Items, which keeps the full history (/action-items?tab=notifications, #8942). The drop-down was Matt's stated preference on 2026-05-26, though he left it open for discussion. He confirmed the routing to the Notifications part on 2026-09-01 and the bell itself on 2026-09-20. CONFIRM — the code matches. The drop-down's "View all notifications" footer is no longer clipped at short heights (#11218 B11).†††‡ (#11218)
  • ✅ notifications.delineation.notification-vs-todo — a notification is closed-loop information: it tells the user something happened that concerns them, or that a third party completed something, such as "your MCR has been completed by the consultant", "your feedback has arrived", or a wellness recommendation prompt. A notification does not create a to-do on its own. A to-do (Action Items) is something this user must act on. When one event both informs the user and needs action (e.g. feedback arriving that the user must complete), it can raise both. So the bell count and the Action Items count can legitimately differ (#8101). Notifications come up in the bell. To-dos are reached through Action Items and its logo control (action-items.header.logo-control, not built, #12141). Several identical to-dos should be grouped rather than flooding the list (grouping drift is #12763). Settled 2026-10-03 (Q4, formerly OQ-N3): this is the rule Matt asked for on 2026-09-01, and his 2026-09-20 statements on #12234 confirm it. ⏳ until Matt confirms the rule he asked for on 2026-09-01 (OQ-N3).††††† (#11218)

Actions Page (renamed from "Inbox" — #3953) ​

  • ✅ Unified Actions tab UI in notifications panel
  • ✅ Existing notifications integrated into unified actions feed
  • ✅ All outstanding items surfaced as action items
  • ✅ Unified actions / action items tab
  • ✅ Nav item and page title renamed from "Inbox" to "Actions" (#3953)
  • ✅ Console errors on actions page resolved (#3952)
  • ✅ Backend aggregation endpoint for unified actions list (#3666)
  • ✅ Work queue elevated as primary actions source with status tracking (#3693)
  • ✅ Smart prioritisation, progress ring, and daily digest (#3702)

Proactive Prompts ​

  • ✅ CPD plan not submitted → action item prompt
  • ✅ CPD hours deficit → prompt to log activities
  • ✅ Annual CPD plan trigger — persistent reminder when plan not submitted
  • ✅ Profile completion trigger — prompt for missing CV, immunizations, supervisor
  • ✅ Proactive task prompting based on user data — CPD hours behind + plan not submitted dashboard banners
  • ✅ Proactive prompt engine — scheduler and evaluator framework (#3695)
  • ✅ Timesheet incomplete trigger — prompt at end of shift/fortnight (#3683)
  • ✅ Weekly wellness questionnaire reminder is delivered by the scheduler, not only by the client-triggered fallback: a dedicated Europe/London-anchored cron tick lands inside the reminder's own Friday 06:00-06:59 London window under both BST and GMT (06:00 since Matt's 2026-05-27 "6am Friday" call on #7606; the tick fires on the hour so the reminder goes out at 6am, not 06:30), so a doctor no longer has to open the app inside a one-hour weekly slot to receive it (#10942, #12758)
  • ✅ notifications.reminders.wellness-weekly-6am-friday — Built in #12758 (PR #12775): the window now opens at Friday 06:00 London and the tick fires on the hour. The weekly wellness questionnaire reminder fires at 6am on Friday. It arrives in the bell and as a push, and tapping it opens the questionnaire straight away, so the user doesn't have to find the button on the Wellness page. CONTRADICT — superseded wording kept visible: "Send a weekly notification to all active users on Friday at 6:30am" (Matt's #3716 brief, 2026-03-24) → Rob's #7606 default "weekly prompt (Monday morning)" (2026-05-27 06:33Z) → Matt: "CHANGE trigger for 6am Friday" (2026-05-27 07:17Z, newest). Matt's 2026-07-14 "push on the Friday morning" is consistent with that. Per-user timezones stay tracked on #11651. wellness.md carries the same 06:30 wording (handoff on #12720).††††‡ (#11218, #12758)
  • ✅ notifications.triggers.scheduled-caller-required — Built in #12759 (PR #12775): processCpdHomeAwayNudges now runs on a daily 22:00 UTC registered tick, only for accounts older than the 60-day away threshold. Every proactive reminder that Matt expects to go out by itself must be fired by a registered schedule: a registerScheduledJob / registerMaintenanceJob call in api-container.ts, or the daily scheduler-lambda handler. An admin-callable procedure alone doesn't count. This is the #11104 lesson ("a function existing doesn't mean it runs") applied to every trigger, as Task 16 asks: review all notification triggers, then show them firing live. The drift this AC found (the CPD Home away nudge from #6362 had no scheduled caller) is fixed by PR #12775. The nudge's content and cadence belong to cpd-home.md (cpd-home.compliance.non-upload-is-non-compliance; handoff on #12720). This spec owns only the "it must actually run" rule, because the processor lives in this spec's code-paths:. The same rule was applied to two more sweeps that had no scheduled caller: the appraisal reviewer non-response reminders (APPRAISAL_REVIEW_REMINDER_TICK, 22:00 UTC, #12756) and the PPP Passport indemnity reminder, indemnity auto-expire and training expiry reminder (PASSPORT_DOMAIN_EXPIRY_TICK, 21:30 UTC, #12810), both registered in api-container.ts (the live NAS backend; scheduler-lambda is the disabled Azure path). The reminders' content and cadence belong to appraisals-wba.md and ppp-passport.md.††‡ (#11218, #12759) Appraisal cadence reminders (calculateAppraisalDueDates) place MCR due dates mid-interval (2 a year → months 3 and 9, #12730).
  • ✅ The fortnightly "submit your timesheet" reminder is delivered by the scheduler at all: processTimesheetSubmissionReminders shipped in #4683 with no scheduled caller — its only invocation was an admin-callable protectedProcedure, so the prompt could not fire on any instant of any day, and a doctor sat on a fortnight of unsubmitted geofence drafts without being prompted. A dedicated tick now drives it, fired every 15 minutes rather than hourly because the eligibility window is 06:00-06:29 in the instance timezone (resolved from instance_config at run time, so Europe/London on UK and Australia/Sydney on AU): an hourly UTC tick lands at :30 past every local hour in a UTC+05:30 zone and :45 in UTC+08:45, entirely disjoint from a minute < 30 window (#11104)
  • ✅ A reminder schedule that can never satisfy its own eligibility window is reported at boot rather than inferred from a fortnight of silence — a missing cron (#11104) and a disjoint one (#10942) are indistinguishable in the logs because neither writes anything, so both reminders carry a startup armed/not-armed self-check (#11104)
  • ✅ Annual registration re-check job persists each registration's verified status and last-checked date (#8327)
  • ✅ Two geofence/timesheet server-side monitors (monitorGeofenceStreamSilence, monitorStuckOpenGeofenceShifts) are registered as admin-callable triggers in this router alongside the existing reconcileMissingGeofences/monitorGeofencePreferences monitors — full AC ownership (thresholds, tuning basis, Open Question on where the signal surfaces) lives in timesheets.md, not here; noted here only because they share this router file (#10916)
  • ✅ Arming a hospital's geotag boundary (processGeofenceActivation.ensureGeofenceForHospital) writes the workplace_locations boundary and the auto-timesheet activation in geo_fence_preferences concurrently, not one after the other; both remain best-effort and neither can fail the hospital attach. Auto-timesheet activation may therefore be set even when the boundary insert fails — the same state the no-coordinates branch already produces on purpose (#10152), and reconcileMissingGeofences re-arms the boundary. Behaviour ownership lives in profile-doctor.md (Add Hospital) and timesheets.md; noted here because the service file is in this spec's code paths (#12552)
  • ✅ Three wellness schedule ticks (WELLNESS_SYNC_TICK, WELLNESS_MORNING_DRAW_TICK, WELLNESS_EVENING_DRAW_TICK) live in this router's schedules.ts alongside the notification ticks above — full AC ownership (cron cadence, wellness-domain gating logic) lives in wellness.md, not here; noted here only because they share this owned file (#11837)

Push Notifications ​

  • ✅ Geo-fence exit → "Complete your timesheet" push

  • ✅ Native push notifications for all app events on mobile (#3610)

  • ⏳ Push notification for each proactive trigger type

  • ✅ notifications.scheduled.shared-idempotency-key — when a scheduled notification can also be produced by a second, non-scheduled generator, every path must write and match on the SAME metadata idempotency key. A path that deduplicates on a key the other never writes is blind to the other's rows and both insert, once per cycle. Live instance: the weekly wellness questionnaire reminder, where the Container Apps Job matched metadata->>'scheduledKey' and the client-triggered app-load path matched metadata->>'date' — both fire in the same Friday 06:30–06:59 London window, so doctors received it twice every week (UAT notifications rows 1186/1207, user 17, 14 min apart). The shared key is week-scoped (wellness:<userId>:<ISO-week-year>-W<week>) so any two dates inside one cycle collapse to one identity, and it is derived from the ISO week-numbering year rather than the calendar year — otherwise a week spanning New Year yields two keys and duplicates once annually. Scheduled reminders are system-generated: senderId is null, never the recipient's own id. (#11311) [src: api/backend-ppp/src/services/notifications/scheduledNotificationService/index.ts, api/backend-ppp/src/services/wellness/wellnessService/notification/weekKey.ts]

  • ✅ notifications.scheduled.idempotency-key-enforced-at-db — the shared idempotency key above must be enforced by the database, not merely checked by an application SELECT. A pre-insert SELECT is advisory: two Container Apps Job replicas, or one replica retried after a partial run, can both pass it and both insert. Live instance: UAT notifications rows 1170/1171 — byte-identical weekly wellness reminders for user 24 with the same scheduledKey written in the same millisecond, after #11311 had already converged both generators on that key. A partial UNIQUE index on (user_id, (metadata->>'scheduledKey')) where the key is not null makes the duplicate unrepresentable, and the insert claims the key with ON CONFLICT … DO NOTHING so the losing writer is a silent no-op rather than an error or a second push. Three properties are load-bearing: the index is keyed on user_id as well as the key, because registration_recheck_summary:<year> is deliberately fanned out to every super admin (one row each) and a key-only index would deliver it to the first admin and silently drop the rest; it is partial, because event-driven notifications carry no scheduledKey and legitimately recur; and the conflict arbiter names this index explicitly, because notifications carries three other unique indexes and a bare ON CONFLICT DO NOTHING would swallow their violations too, turning a real bug into a notification the doctor never receives. (#11312) [src: packages-shared/ppp/drizzle/0228_notification_scheduled_key_unique.sql, api/backend-ppp/src/services/notifications/notificationService/index.ts]

  • ✅ notifications.push-token.single-owner — a device push token is bound to exactly one user at a time, and the binding is always to the caller. An Expo push token identifies an installation, not a person: the same device reissues the same token to whoever logs in next, and logout is local-only so nothing is deregistered server-side. Two consequences, both reachable only once the mobile client actually began POSTing tokens (saveNotificationToken had zero production callers before #11491). (1) Cross-user collision. The unique index on user_notifications is (user_id, platform, token) — three columns — so (A, ios, T) and (B, ios, T) do not collide and coexist; the service looked up and updated on (userId, platform) only, never considering other users holding the same token, and sendPushNotification selects every row for a userId with no cross-user check. On a shared ward or theatre device, user A's notifications — carrying timesheet and hospital identifiers — would render on user B's lock screen indefinitely. The save now deletes any row whose token matches the incoming one and whose userId differs from the caller, scoped on token rather than platform because the same token string on a different platform row is still the same physical device. (2) Caller identity. enforceUserScope returns the client-supplied userId unchanged for super-admin callers, so an admin could bind a token to another user's account; registering a device is purely self-referential, so the procedure resolves the caller's own id via getSelfUserId and ignores the client-supplied userId entirely. Token input is bounded to the varchar(500) column width. Guarded by a real-database integration suite rather than a mocked one — the collision is a property of what the real three-column index permits, and a Drizzle mock chain has no index, so a mocked red would prove only what the mock was told to return. Coverage note, corrected after an initial false claim: an earlier version of this AC stated the integration suite "runs only locally today" and cited #11527 as an open gap. Re-derived rather than trusted: .github/workflows/integration-tests.yml invokes vitest directly (npx vitest run --config vitest.integration.config.ts), not via the test:integration script name, so grepping for that script name (the method the earlier claim used) finds nothing while the suite genuinely runs — on every push to uat, nightly, and on dispatch, 211 files green in ~7 minutes including this one. #11527 was re-derived on that evidence and closed as not-a-defect. The real, narrower gap: only the bounded integration-smoke subset runs pre-merge per-PR; the full suite (including this one) runs post-merge on uat, so a regression here would surface ~25 minutes after merge rather than blocking the PR itself — an accepted, pre-existing architecture (#6469), not something this AC introduces. This is the second of the two remedies #11507 proposes and the one that issue names as more robust, because it self-heals devices where sign-out never cleanly fired (app deleted, session expired, crash). The first remedy — an explicit deregistration call from the mobile sign-out path — is now implemented (#11507), closing the window where a user signs out and nobody else signs in, in which no save occurred to trigger the release. That shape was a hygiene gap rather than cross-user disclosure (the device is held by the row's own owner); see notifications.push-token.released-on-sign-out below. Note removeInvalidTokens covers neither shape: it reaps only tokens Expo reports invalid or expired, and a shared-device token stays valid. (#11491, #11507) [src: api/backend-ppp/src/services/notifications/userNotificationTokenService/index.ts, api/backend-ppp/src/routers/procedures/notifications/userNotificationToken/index.ts, api/backend-ppp/src/services/notifications/userNotificationTokenService/sharedDeviceTokenScope.integration.test.ts]

  • ✅ notifications.push-token.released-on-sign-out — signing out releases that device's token, so a signed-out user stops being reachable on it. The AC above binds a token to one user at a time but only ever acts on a save, so it cannot help where a user signs out and nobody signs in after them: the row survives, and sendPushNotification — which selects every row for a userId with no liveness check — keeps delivering that user's clinical content to a handset sitting on the login screen. deregisterNotificationToken deletes on (userId, token), and the deregister procedure takes no userId input at all (not even an ignored one, unlike save, which must accept and discard it for wire compatibility), resolving the caller via getSelfUserId — so a user can never deregister another user's device, and the widening that would allow it is exactly the mutation the tests pin. Scoping on token rather than userId alone keeps the signing-out doctor's other devices working. Idempotent by construction: deleting an absent row is a no-op, so a retried or duplicated sign-out is harmless, and callers treat failure as non-fatal because the save-path release is the backstop for any sign-out that never reached the server (offline, crash, or losing the race against session teardown). Guarded by the same real-database integration suite as the AC above and verified by mutation — dropping the userId predicate turns the cross-user guard red. (#11507) [src: api/backend-ppp/src/services/notifications/userNotificationTokenService/index.ts, api/backend-ppp/src/routers/procedures/notifications/userNotificationToken/index.ts, api/backend-ppp/src/services/notifications/userNotificationTokenService/sharedDeviceTokenScope.integration.test.ts]

  • ✅ notifications.push.geofence-exit-opens-entry — the geofence exit push says the user has been tagged leaving work and to complete their timesheet entry. Tapping it opens that entry. (CONFIRM: Matt restated this on 2026-03-24 and 2026-05-06. The behaviour and its duplicate-fire fixes are owned by timesheets.md.)†† (#11218)

Email Templates & Preferences ​

  • ✅ CPD approval email shows recipient name and allocated hours (#4824)
  • ✅ Notification preference UI — per-category opt-out matrix per Q1 above (#4979 — proactive nudge categories togglable in the Settings tab on Action Items (/action-items?tab=notifications), alongside Unread and All; transactional notifications stay mandatory; server gates createNotification against the user's disabledTypes). The panel was originally built into notification-centre, which #3796 unrouted on 2026-03-24 when notifications consolidated onto Action Items — leaving this AC marked ✅ while no user could reach the UI, because its unit tests render the component directly and stayed green regardless of routing. Mounted on the live surface by #12088, with a @regression scenario that fails when the tab is absent and a persistence assertion that survives a reload (a local-only state change would otherwise satisfy "the category should be turned off"). [src: instances/ppp/src/modules/notifications/unified-inbox/components/NotificationFeed.tsx, instances/ppp/src/modules/notifications/notification-centre/NotificationPreferences.tsx]
  • ✅ notifications.force-deliver-transparency-types — createNotification accepts an internal-only options.forceDeliver flag that bypasses the disabledTypes opt-out check above for a specific call, reserved for access-transparency notifications a recipient must always receive regardless of preference (e.g. the super-admin support-view access notice, super-admin.md § "Privacy policy — consent/notify"). Deliberately NOT a field on CreateNotificationSchema/CreateNotificationParams — that schema doubles as the client-facing tRPC input for notifications.create, so a schema field would let any authenticated caller force-deliver arbitrary notification types; it is threaded as a second function parameter instead, opt-in per call site, with every other createNotification call site unaffected. (#11056 AC3) [src: api/backend-ppp/src/services/notifications/notificationService/index.ts — CreateNotificationOptions.forceDeliver]

Performance & Caching ​

  • ✅ notifications.perf.backend-cache — getActionItemCount and listNotifications cache results per-userId in Redis with a 20-second TTL (TTL_NOTIFICATIONS = 20 in ppp-cache.ts), using the PppCache utility. Cache keys are namespaced ppp:notifications:*:<userId> for surgical per-user invalidation via delPattern. Cache degrades gracefully: all PppCache calls are fire-and-catch; SKIP_REDIS=1 bypasses the cache and falls through to Postgres. (#9230)
  • ✅ notifications.perf.write-invalidation — createNotification, updateNotification, bulkMarkAllAsRead, markAllAsReadForCaller, and markAllSeen all call invalidateNotificationCache(userId) after their DB write, ensuring a newly written notification clears the cache immediately and appears on the recipient's next poll (within ≤20s, not one full TTL later). (#9230)
  • ✅ notifications.perf.frontend-poll-throttle — Frontend refetchInterval raised from 15s → 30s; staleTime set to 20s (matches backend TTL); refetchIntervalInBackground changed from true → false so background tabs stop polling Postgres on every 15s tick. (#9230)
  • ✅ notifications.task-manager.group-title-distinguishes-status — on the Task Manager page a grouped to-do card's title names the status its members share, so two groups of the SAME record type that differ only by status never render as two visually identical cards, and a group of completed records is not labelled "drafts". Grouping already keys on the composite type:wbaType:status; buildGroupTitle previously interpolated only the type. Realises the same behaviour as logbook.entry.todo-group-title-distinguishes-status — that spec owns the grouped stepped-flow requirement (#8101), while the components themselves live under instances/ppp/src/modules/notifications/unified-inbox/, which this spec's code-paths: govern.†‡ (#11217)
  • ✅ notifications.task-manager.no-metadata-editor-on-cards — the admin status / due-date / assignee / tags editor (TaskMetadataBar, #11779) is gone from To-do cards for every role. AC ownership lives in action-items.md (action-items.todo.no-triage-overlay); noted here only because the deleted component sat in this spec's code paths (#12762)
  • ✅ notifications.task-manager.todo-headline-standardized-copy — each To-do card's headline reads "[Verb] [Subject] — due [date]" (e.g. "Sign off Dr Smith's WBA (MCR) — due Fri 8 May") instead of a bare originator name plus type chip, and threads a deadline field through the underlying WorkInProgressItem/PrioritisedTodoItem pipeline so the To-do list sorts deadline-ascending with no-deadline items dropping to the bottom. Same code-path/behaviour split as the group-title AC above — docs/features/action-items.md's To-do tab AC (Q2/Q5) owns the behavioural requirement, this spec's code-paths: govern the component files. No source WorkInProgressItem type (wba/feedback/reflection/auditEvent/logbookCase/timesheet/ppp360/timesheetBatch/360_supervisor_review) stores a real due-date today, so deadline is null everywhere and the sort is a correctly-scoped no-op against current data until a source type populates a real deadline.†‡ (#12327)
  • ✅ notifications.task-manager.todo-headline-own-item — when the viewer IS the originator of a To-do item (their own draft on their own list), the headline addresses them — "Complete your WBA (PBA)" — instead of naming them in the third person; other people's items keep "{name}'s". TodoItemCard passes the signed-in user's id to buildTileHeadline. Behaviour is owned by docs/features/action-items.md (Tile detail); this spec's code-paths: govern the files.† (#12709)
  • ✅ notifications.task-manager.group-expand-per-case — a grouped To-do card has a "Show N cases" toggle ("Show N items" for non-logbook groups) listing each member (draft logbook cases by operation text and case date, from the work queue's procedureLabel/caseDate; other drafts by their own title and record date, #12763), each with Open (that record) and — for the viewer's own activity-backed drafts only (isOwnDeletableDraft) — Delete after a confirm dialog; clicking the card itself still starts the stepped flow. Each row's Open and Delete carry a title naming that row (the visible label stays "Open"/"Delete", no aria-label override, #7773), so rows are distinguishable to assistive tech (#12828). Behaviour is owned by logbook.entry.todo-group-individual-oversight in docs/features/logbook.md; the components live under this spec's code-paths:.† (#12724, #12763)
  • ✅ notifications.perf.action-items-badge-poll — the dashboard Action Items badge (checklist icon, RecentActionItemsMenu.tsx, fed by todoList.getPrioritised — a separate counter from the Notification bell badge above, which is fed by getActionItemCount; the two are not expected to show the same number) now polls every 30s (refetchInterval, mirroring the bell badge's pattern directly above), and stops polling on a query error. The query is a live, uncached Postgres read (unlike the bell's getActionItemCount, which has an explicit Redis layer) — it had a staleTime but no refetch trigger and no mutation anywhere invalidated it, and combined with the app-wide refetchOnWindowFocus: false default (queryClientDefaults.ts, #10251 — deliberately disabled repo-wide to stop a different WebView-refocus memory crash), the badge fetched once per mount and never refreshed again for the lifetime of the app session — a genuine defect regardless of what any specific count was doing. On the live UAT report that surfaced this (Matt's badge read "15" on both 17 Jul and 22 Jul), a direct count against the underlying tables afterwards returned 17 for the same user — proof the count itself moves and is not stuck or wrong at source — while Log Analytics showed only one work-queue-affecting event (a 2-case logbook import) for that user across the entire 17-22 Jul window. The most likely reading is that the count genuinely was 15 that week and the badge was accurate — this fix does not claim to have corrected a frozen number Matt actually saw wrong; it closes a real "won't refresh while the app stays open" gap that would show a stale count the next time it does change mid-session, which is exactly when a doctor is working through their queue. † ‡ (#10931)

Admin Configuration ​

  • ✅ notifications.admin.schedule-builder — super-admin settings page (/settings/notification-schedule) for authoring notification schedules: name, active toggle, send frequency (once/daily/weekly/monthly), send time, audience filter (account type, optional speciality/hospital IDs), message title/body, and an optional deep-link target. Backed by a notification_schedule table and ppp.notifications.notificationSchedule.* router, following the createSettingsCrud factory pattern. Config CRUD only — no processXxxNotifications.ts processor reads this table yet; wiring a scheduler to evaluate and fire these schedules is a separate follow-up. All five procedures (create/update/delete/list/getById) are adminProcedure-gated — read access is admin-only because rows hold unsent draft message copy and hospital/speciality audience-targeting data, not public reference data, so the sibling jobTitles/keywords pattern of a broader protectedProcedure read scope does not apply here. (#11768) [src: api/backend-ppp/src/routers/procedures/notifications/notificationSchedule.ts, packages-shared/ppp/src/schema-groups/notifications/notificationSchedule.ts]

  • ✅ notifications.admin.automated-email-templates — super-admin settings page (/settings/automated-emails) listing every automated email type with an on/off toggle and editable send timing (immediate, or N minutes/hours/days after trigger). Covers the fixed catalog named in the issue: Welcome, CPD Activity Approval, CPD Provider Process, WBA (request/reminder/completed/assessor-invite), Feedback, Reflections, Logbook Case (verification/competency), Appraisals (scheduled/reminder/completed/overdue), Timesheet approver notification, and Approved-Timesheet→Admin/Payroll — 17 rows total. Backed by a fixed-catalog automated_email_template table (row identity is the emailType enum, not admin-authored) and ppp.notifications.automatedEmailTemplates.* router, following the createSettingsCrud factory pattern used by notificationSchedule above. Config CRUD only — no email-send call site reads this table yet; every current send (sendEmail in mailer-helper.ts) is called directly from its owning service with hardcoded copy/timing, so wiring a generic send pipeline to consult this table is a separate, larger follow-up, not a trivial addition. All five procedures (create/update/delete/list/getById) are adminProcedure-gated for the same reason as notificationSchedule — timing/toggle config for regulated clinical flows (WBA, appraisals) is admin-internal, not public reference data. (#11769) [src: api/backend-ppp/src/routers/procedures/notifications/automatedEmailTemplates.ts, packages-shared/ppp/src/schema-groups/notifications/automatedEmailTemplate.ts]

  • ⏳ notifications.admin.trigger-catalogue — partly built (#12760, #12548). Built and live-proven 2026-10-05 (@issue-12548): the Notification Triggers console lists every trigger, an admin can edit its occasion, recurrence and (for the eight re-timeable reminders) a validated cron and timezone schedule, switch it off, and change where it lands; the senders and scheduler read those settings. Not built: editing the audience, the wording and the click-through. The admin console has an editable Notification schedule table listing every notification trigger, one row each. Each row shows and lets an admin change: the audience (a user type, or a specific user), the timing and recurrence (the occasion, either an event or a schedule, and how often it repeats), the wording of the notification, and the click-through (where the user lands when they tap it). It has no 12-month calendar view. CONTRADICT, superseded wording kept visible: "its occasion (an event, or a schedule), its recurrence, and the next year of firings" (shape left open as OQ-N2) → Matt's ADMIN CONSOLE page (2026-08-04) describes an editable schedule with audience, timing, wording and click-through (Q3, closed 2026-10-03). The table covers the triggers that really run (the hard-coded jobs in api-container.ts and the reminders raised by individual services), not just the unwired config tables above. Before #12548 nothing like this existed: /settings/notification-schedule (notifications.admin.schedule-builder) has the right columns but holds only admin-authored rows that no sender reads, /settings/automated-emails is the same, and the live triggers are visible only in code. An admin can also fire any of the eight re-timeable scheduled reminders on demand with a Run now button in the row's detail (#12964); it runs the same job the scheduler runs, for every user it applies to, behind a confirm, and is recorded in the audit trail. The MCR / MSF / 360 cadence reminder (appraisal_reminder) is catalogued as a Platform Reminder (#12966). Each row carries an editable "goes to To-do / Notifications / both" column (action-items.md Q9, closed 2026-10-05).†† (#11218, #12760)

Status ​
Sub-featureStatusNotes
Event-driven notifications (WBA, feedback, etc.)✅ BuiltDeep-link bugs fixed #3549, #3575–3580
Notification bell with badge✅ BuiltDuplicate bell bug fixed #3541
Actions page UI (was "To-Do tab")✅ Built
Existing notifications in actions feed✅ Built
All outstanding items as action items✅ Built
Page named "Action Items"✅ Built#3953 → #11767 → #12326; owned by action-items.md
Console errors on actions page✅ Fixed#3952
CPD plan / deficit proactive prompts✅ Built
Profile completion prompt✅ BuiltLive to-do items (todoListService getProfileCompletionItems). processProfileCompletionNotifications has no caller at all (dead code, found 2026-10-03)
Backend to-do aggregation endpoint✅ Built#3666
Work queue status tracking✅ Built#3693
Proactive prompt engine (scheduler)⚠️ Drift#3695 built; CPD Home away nudge has no scheduled caller — #12759
Smart prioritisation + progress ring✅ Built#3702
Timesheet incomplete trigger✅ BuiltVia geofence exit push + fortnightly reminder (#11104). processTimesheetIncompleteNotifications has no caller (dead code)
Weekly wellness reminder at 6am Friday✅ BuiltFires 06:00–06:59 London (#12758); a Platform Reminder (Platform Reminders tab, not the bell: Rob 4 Oct 2026; Matt's 27 May call on #7606 said the bell, to confirm)
Wellness morning readiness + evening sleep prompts✅ Builtwellness_morning_prompt (05:00-11:59 London) and wellness_evening_sleep_prompt (from 18:00 London, off shift, outside geofence); one per user per day (scheduledKey), registered in the trigger registry (migration 0268)
Bell drop-down (latest 5) vs Action Items✅ BuiltConfirmed against Matt 2026-05-26 / 2026-09-01 / 2026-09-20
Notification vs to-do rule✅ SettledQ4 (was OQ-N3), closed 2026-10-03
Admin catalogue of all notification triggers📋 Specified#12760 — editable Notification schedule table (Q3, was OQ-N2)
Native push notifications (mobile)✅ Built#3610
Bell as single entry for all reminders✅ Built#3611
Mobile bell position✅ Fixed#3972
Bell badge undercounts > 5 unread✅ Fixed#4974
Mark-all-as-read bulk endpoint✅ Fixed#4980
WBA assessor email for external assessors✅ Built— token-based email invitation flow added
CPD approval email content✅ Built#4824 — cross-labelled with CPD
Per-category notification opt-out UI✅ Built#4979 — Notifications → Settings tab; server-side gate

Open issues on label:feature:notifications (1)

#Title
#12760feat(notifications): admin catalogue of all notification triggers — occasion + recurrence over 1 year (Task 16 brief)

Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.

Change Log ​
DateChangePR/IssueReason
2026-10-05The console''s "Lands in" column now describes the real destination. The routing model gains Platform Reminders and To-do and Platform Reminders (migration 0268); scheduled reminders in PLATFORM_REMINDER_TYPES default to them, the server refuses a destination a notification cannot reach, and an admin''s routing choice takes effect. The Schedule, Lands in, Active and Edit controls fit at 1440px (occasion, audience, wording and link moved to an expandable detail row), and routing and Active saves confirm with a snackbar. Catalogue text for the fortnightly timesheet reminder, the incomplete-timesheet prompt and the CPD deadline reminder now matches the processors. The CPD milestone and timesheet cooldown dedupe queries use the real user_id column (they errored for every user who reached a milestone). "Send test to me" delivers to the admin and reports honestly when it does not. Scheduled and platform reminders are raised with a null sender, and the weekly wellness reminder skips admin accounts. A rejected notification schedule shows the validation reason.#11218, #12548, #12764Task 16 recording audit of 5 Oct 2026 (B2, B3, B4/C1, B5, B7, B8, B10, B16, B17), Rob''s decision to make the console true. Live @issue-11218 scenarios were red against the old routing labels and the 1637px table, and green after; backend regressions were red against the old code (column "userId" does not exist; forceDeliver missing; sender stamped as the acting admin).
2026-10-05notifications.admin.trigger-catalogue stays partly built: occasion, recurrence, cron and timezone schedule, the off switch and the "lands in" routing are editable and live-proven (@issue-12548 scenarios red then green on an isolated stack). The audience, wording and click-through are still read-only and keep the AC open.#12548, #11218Only the scenarios that prove an acceptance criterion flip it; the trigger catalogue names audience, wording and click-through editing too, which are not built.
2026-10-05The PPP Passport staff review queue at /admin/passport-reviews now spans every Passport domain (with a document viewer and an immunisation / Passport-document section), and the indemnity, indemnity-expired and training expiry notifications deep-link to /ppp-passport. See the ppp-passport spec change-log entry for the full set.#12893, #12896, #11212Task 13 audit defects D2, D5 and D9 (5 Oct 2026); covered by @issue-12893 in ppp-passport.feature.
2026-10-05The Notification Triggers console has a Run now button for the eight re-timeable scheduled reminders (super admin only, confirm, audit entry), and the MCR / MSF / 360 cadence reminder appraisal_reminder plus the CPD plan submission prompt are catalogued as Platform Reminders.#12964, #12966, #11218Task 16 reachability check (5 Oct 2026) R16-33 and R15-28/R15-36; covered by @issue-12964 and @issue-12966 in super-admin.feature. Wave 2 lane; Matt closes #11218.
2026-10-04The Notification Triggers console is now live end to end. A super admin can edit each trigger's occasion, recurrence and, for the eight re-timeable reminders (weekly wellness, CPD plan, CPD plan submission, CPD deficit, CPD at-risk, CPD deadline, CPD Home away nudge, appraisal reviewer reminder), a validated cron and timezone schedule override, and switch a trigger on or off. Every edit is audited (notification_trigger entity on the audit trail). The senders read the registry: createNotification raises nothing for a trigger that is off or routed to To-do only, and the scheduler yields its built-in tick to an override and fires the override through a shared 15-minute dispatcher. Migration 0262 adds schedule_cron and schedule_timezone; the defaults mirror the hard-coded ticks, so behaviour is unchanged until an admin edits.#12548, #12760, #12764, #11218Rob 4 Oct 2026: an editable console whose settings change what runs, so it cannot drift. Not built: editing audience and wording; schedule override for the reminders that run in the shared daily bundle (appraisal and registration due-date notices, passport expiry) or in processor-owned windows (fortnightly timesheet reminder); a set of event types still raises on its own path. Those show their schedule read-only.
2026-10-04Slices 1-3 of notifications.admin.trigger-catalogue built, AC left open: a notification_trigger registry (migration 0257, seeded from NOTIFICATION_TRIGGER_CATALOGUE) lists every trigger with channel, occasion, recurrence, audience, wording and click-through on a super-admin Notification Triggers page, and an admin can change where each lands (To-do, Notifications or both). Still open: editing audience, timing and wording, and the runtime reading the routing and schedule overrides. #12547 email on/off: notification_preferences.email_enabled plus a Settings-tab switch; the optional CPD at-risk email honours it, mandatory emails ignore it.#12548, #12760, #12764, #12547, #11218Rob decided on 2026-10-04 to build an editable admin console (#12548 comment) and approved the migrations. The AC is not flipped to done because only routing and active are editable and nothing at runtime reads them yet.
2026-10-04'Mark all as read' now marks every unread notification of the caller read on the server (new notifications.markAllRead procedure / markAllAsReadForCaller, scoped by user and unread only, no id list) instead of PATCHing only the rows the feed or bell menu had loaded. Both surfaces call it, then refresh the server totals. bulkMarkAllAsRead (explicit ids) stays.#12564Bug #12564 from the Task 16 walkthrough follow-ups: with 67 unread and 20 loaded, 'Mark all as read' lowered the count by the loaded unread rows, not to zero. Closes the 'Not changed' note in the #12545 entry. Not changed (open product question, #12563): the bell badge still counts unseen rows (seenAt IS NULL) and the Unread tab unread rows (isRead = false); marking all read touches isRead only.
2026-10-04Appraisal cadence reminders for MCR now fall halfway through each cadence interval (2 a year → end of month 3 and month 9) instead of counting back from the end of the period. MSF and 360 reminder dates are unchanged.#12730Issue #12730: Matt (#11144, 2026-09-29) asked for MCRs at months 3 and 9; calculateAppraisalDueDates feeds the reminder notifications. Rob decided it applies to all users (4 Oct).
2026-10-04Two more reminder sweeps that had no scheduled caller are now registered in api-container.ts: the appraisal reviewer non-response reminders (APPRAISAL_REVIEW_REMINDER_TICK, daily 22:00 UTC) and the PPP Passport indemnity reminder, indemnity auto-expire and training expiry reminder (PASSPORT_DOMAIN_EXPIRY_TICK, daily 21:30 UTC).#12756, #12810The #11104 lesson (a function that exists is not a job that runs) applied to #12756 and #12810. The tick specs live in scheduledNotificationService/domainReminderSchedules.ts, which this spec owns.
2026-10-04The admin Task Manager metadata editor (TaskMetadataBar: status, due date, assignee, tags) added by #11779 is removed from To-do cards and its component deleted. The To-do cards live under the Action Items spec; see its action-items.todo.no-triage-overlay.#12762, #11217Matt, 2026-09-20 (#12234): the per-card triage editor is "drift and overkill".
2026-10-04notifications.task-manager.group-expand-per-case widened: Delete is offered for the viewer's own activity-backed drafts of any type (isOwnDeletableDraft), not only logbook drafts; non-logbook members are labelled by their own title and record date (new work-queue title, caseDate now set for every draft activity).#12763Generic side of #12724 (#12763, Matt 2026-08-04). Behaviour is owned by action-items.todo.group-individual-oversight; the component files sit under this spec's code-paths:.
2026-10-04notifications.task-manager.group-expand-per-case: each expanded row''s Open and Delete buttons carry a title naming the row. notifications.task-manager.todo-headline-standardized-copy: a To-do tile no longer shows the third-person headline ("Complete <name>''s …") before the viewer loads; it shows the type alone until the viewer resolves.#12828, #12763#12828 review follow-up on #12827/#12763: every row shared one accessible button name, and the user's own item briefly read in the third person.
2026-10-03Weekly wellness questionnaire reminder window moved from Friday 06:30-06:59 to Friday 06:00-06:59 Europe/London, and the dedicated London-anchored tick now fires on the hour (0 * * * *) so the reminder goes out at 6am. The week-scoped idempotency key is unchanged. Built in #12758.#12758Matt on #7606 (2026-05-27): "CHANGE trigger for 6am Friday" — newest dated statement, superseding his own #3716 "Friday at 6:30am" brief. The code still used 06:30.
2026-10-03Phase C open questions closed from existing evidence (Rob approved 2026-10-03). The three questions are renumbered so the AC-index parser can see them (OQ-N1 → Q2, OQ-N2 → Q3, OQ-N3 → Q4) and moved to a new Closed Questions block. Q2 (push on/off) closed with no separate push master switch. Q3 (admin trigger console) closed as an editable Notification schedule table (audience, timing and recurrence, wording, click-through; no calendar), and notifications.admin.trigger-catalogue is rewritten to match, with the old "next year of firings" wording struck through. Q4 (notification vs to-do) closed, and notifications.delineation.notification-vs-todo is now settled (✅). The one follow-up, whether the To-do / Notifications / both column is admin-editable, lives only in action-items.md Q9.#11218, #12760Research on 2026-10-03 against Matt's ADMIN CONSOLE Notion page (2026-08-04), #11218, #12234 (2026-09-20) and the 2026-03-24, 2026-05-26 and 2026-09-01 transcripts. New source fragment notion-admin-console. Spec-only; no BDD scenarios added, per the spec-refresh rule.
2026-10-03The notifications spec was refreshed for Async Task 16 (#11218). Two drift ACs were added. notifications.reminders.wellness-weekly-6am-friday (#12758) is drift because the reminder fires at 06:30–06:59 London, but Matt's newest instruction (#7606, 2026-05-27) is 6am Friday. The #10942 AC keeps its scheduled-delivery claim, and its 06:30 window is marked superseded. notifications.triggers.scheduled-caller-required (#12759) is drift because processCpdHomeAwayNudges has only an admin-callable caller. One new not-built AC, notifications.admin.trigger-catalogue (#12760), comes from the Task 16 brief. Two ACs confirm what is built: notifications.bell.heads-up-dropdown and the geofence-exit push. One new pending AC, notifications.delineation.notification-vs-todo, waits on OQ-N3. New Open table: OQ-N1 (push on/off option), OQ-N2 (trigger console shape), OQ-N3 (notification vs to-do rule). The Status table was brought in line with the ✅ ACs. It had stale ⚠️/📋 rows for work long since shipped. status: is now partial-drift.#11218, #12758, #12759, #12760Async Task spec refresh, Task 16 (#11218). The newest dated statement from Matt wins. A read-only check of every process* trigger in scheduledNotificationService/ looked for a real scheduled call site (in api-container.ts or scheduler-lambda.ts), not just a function that exists.
2026-10-03Added notifications.task-manager.todo-headline-own-item (own To-do items read "Complete your …") and notifications.task-manager.group-expand-per-case (grouped To-do cards expand to list each member with Open/Delete) — code-path ACs for behaviour owned by action-items.md and logbook.md respectively.#12709, #12724Both fixes touch instances/ppp/src/modules/notifications/unified-inbox/, which this spec's code-paths: govern; #12709 was a live UAT copy defect, #12724 is Matt's 4 Aug request for per-case oversight of grouped drafts.
2026-09-28createNotification now distinguishes an explicit senderId: null (deliberately anonymous) from senderId: undefined (caller did not say — default to the acting user from ctx.identity). Only the undefined case falls back; a null sender stays null and createdBy stays unset. Five producers pass null through createNotification and now store no sender: supportView.ts, cpdReminderSettings.ts, resolveSpeciality.ts, geoFenceNotification.ts and wellnessService/notification (four other system producers insert directly and are unaffected). support_view_accessed, timesheet_geo_fence_review and speciality_mapping_unmapped are added to SYSTEM_GENERATED_NOTIF_TYPES so the senderless rows render "PPP System" rather than the sender_id-null "Consultant" role label; timesheet_geo_fence_review joins the Timesheet reminders category and speciality_mapping_unmapped is mandatory. Migration 0253 (data-only, .first-apply.validate.sql) clears sender_id/created_by from support_view_accessed rows written before the fix. notifications.list joins only the sender''s id, firstName and lastName. The client-callable notifications.create stamps the caller as senderId/createdBy whatever the client sends and rejects system-generated or mandatory types with BAD_REQUEST.#12566, #12542, #8168, #11056, #11313Privacy defect found in the 28 Sep Async Task walkthrough (#11218 Task 16): the "A PPP team member viewed your account" notice rendered the super admin who opened Support View as its sender. supportView.ts passes senderId: null by design (#8168 data minimisation), but the !params.senderId guard treated null like undefined and resolved the caller from ctx.identity.email. The #12566 review found two consequences of the fix on its own: rows written before it still returned the admin''s whole users row to the recipient through the list join (hence the backfill and the narrowed join), and keeping an explicit null anonymous meant any signed-in user could send an unattributable "PPP System" notification through notifications.create (hence the caller stamp and the type rejection). The AC text under #11313 that described the old fallback as current behaviour is updated in the same change.
2026-09-28notifications.getActionItemCount now also returns feedUnreadCount (every notification with isRead = false) and feedTotalCount (every notification the user has). NotificationFeed — the Action Items → Notifications surface — reads its 'Unread (n)' / 'All (n)' tab labels from those server totals through a new pure helper, resolveFeedTabCounts, falling back to the loaded rows only while the counts request is in flight. An optimistic mark-as-read comes off the unread total immediately. A cached count entry written before this change lacks the new fields and is treated as a cache miss.#12566, #12545, #4974, #12328Found in the 28 Sep Async Task walkthrough (#11218 Task 16): the tab labels only covered the first page of 20 loaded rows while the bell showed 67+. The feed pages 20 at a time and counted notifications.filter(...) over whatever had been paged in — the same defect #4974 fixed for the bell badge, never applied to the feed. feedUnreadCount and the bell's unreadCount are different predicates and can legitimately differ: the bell counts seenAt IS NULL and is cleared by opening the bell (#8978), while the Unread tab filters on isRead = false, which only a per-row action changes. The Unread label uses the predicate the tab itself filters on, so the label always matches the rows behind it. Not changed: 'Mark all as read' still marks only the rows loaded so far (bulkMarkAllAsRead takes explicit ids, #4980), so with 67 unread and 20 loaded it lowers the count by the loaded unread rows, not to zero.
2026-09-28processCpdProviderVerificationReminders now keys its scheduledKey on (activityId, stage) instead of (activityId, calendar day), with exactly two stages — the notice once the 14-day token TTL lapses, and one final reminder at 2 x TTL (28 days) — and never a third. Legacy date-keyed rows count as stage 1 already sent, so an account that accumulated the daily copies gets at most one final reminder and then nothing. The message names the activity (catalogue name, falling back to the description, then activity #&lt;id&gt;) and the provider in both stages; metadata carries stage and activityTitle.#12566, #12546, #5778Found in the 28 Sep Async Task walkthrough (#11218 Task 16): the same 'RACS did not verify your CPD activity within 14 days' arrived every day with no end (30+ copies) and never said which activity it was about. The (activityId, date) key made each daily tick a 'new' notification, so the once-per-day idempotency guard was the thing producing the daily stream. Cadence choice (14d + one 28d final) is engineering-led — neither cpd.md nor cpd-provider-recognition.md states a follow-up cadence — and is recorded as an Open Question for Matt to ratify or change; the bound and the copy live in one place (resolveProviderFollowupStage / buildProviderFollowupMessage) so a different cadence is a constant change.
2026-09-28Every system-generated notification type now belongs to a preference category or is explicitly mandatory. cpd_provider_unverified_followup, cpd_at_risk_quarterly and cpd_deadline_reminder join CPD reminders; appraisal_completion_nudge joins Appraisal & review reminders. A new MANDATORY_NOTIF_TYPES list names the types a recipient can never mute (support_view_accessed), so 'in no category' is a tested defect rather than an ambiguous state. The three scheduler-raised types above are also added to SYSTEM_GENERATED_NOTIF_TYPES, per the existing AC that every scheduler-raised type is enumerated there.#12566, #12547, #4979, #12546Found in the 28 Sep Async Task walkthrough (#11218 Task 16): the RACS verification follow-up was in no category, so Settings offered no way to turn it off. The settings UI builds disabledTypes from the category map and createNotification gates on the raw type, so an uncategorised type is unmutable by construction. Out of scope — separate email on/off toggle: Q1 (#4979) records 'Email channel is independently togglable from in-app channel' as an engineering-led resolution still awaiting Matt's ratification, and no acceptance criterion in this spec carries it. There is also nothing for a toggle to control yet: notification_preferences has no per-channel column, and no email send path consults user preferences (sendEmail is called directly by each owning service — the same gap the notifications.admin.automated-email-templates AC documents). Building it means a schema migration plus a preference gate on every email send site, which is a feature, not this bug fix. Known limitation: a user who muted CPD reminders or Appraisal reminders before this change has only the old type strings in disabledTypes; the category renders as off, but the newly added types are muted only once they toggle the category again.
2026-09-20Updated this spec's "Naming" callout and the surrounding prose, which still pinned the page name to "Task Manager" (#11767) — the naming reverted to "Action Items" per Matt's #12234 confirmation, reconciled by action-items.md (this spec's superseding owner) via #12326. NotificationFeed.tsx's local filter/pagination state also now persists across Action Items tab switches (ActionItemsTabPanel keeps inactive panels mounted, hidden via display: none, instead of unmounting them) — no AC change, listed here because this spec's code-paths: govern that file.#12342, #12326, #11779, #12234action-items.md already states "This spec supersedes notifications.md" and has used "Action Items" naming since #12326's PR1, but this spec's own Naming callout was never updated to match — a stale naming pin that would otherwise keep contradicting the current spec of record. Recorded per CLAUDE.md's "update the spec with the reason in the Change Log" rule rather than silently drifting.
2026-09-20TodoItemCard's headline changed from a bare originator name + type chip to a standardized "[Verb] [Subject] — due [date]" line (new tileCopy.ts), and its underlying TodoItemData/WorkInProgressItem pipeline gained a threaded deadline field used by the To-do sort order. Retired the stale #8629 "mark as done Undo" BDD scenario in action-items.feature, which clicked a "Mark as done" button already removed by #8653.#12327This spec's code-paths: govern the unified-inbox component files by convention (see the notifications.task-manager.group-title-distinguishes-status AC above, which notes the same split — behavioural ownership sits with docs/features/action-items.md's To-do tab AC (Q2/Q5: deadline-ascending sort, "[Verb] [Subject] — [deadline]" tile copy), while the component files live under this spec's code-paths. See docs/features/.changelog/action-items/2026-09-20-issue12327.md for the full behavioural change record.
2026-08-31Mounted the per-category notification opt-out panel on the live Action Items surface as a third "Settings" tab beside Unread and All.#12094, #12088, #4979The opt-out UI (#4979) was built into notification-centre, which #3796 unrouted on 2026-03-24 when notifications consolidated onto /action-items. That left a complete, styled, backend-wired feature reachable by no user, while the spec recorded it as built and its 21 unit tests stayed green — they render the component directly, so routing is invisible to them. The @smoke scenario that should have caught it navigated to /notifications and then clicked the tab behind if (await tab.isVisible()) await tab.click(), making an absent tab a silent no-op. This PR mounts the existing component unchanged, removes that no-op guard, and adds a reload-survival assertion so a local-only state change cannot satisfy the test.
2026-08-30On the Task Manager page a grouped to-do card's title now names the status its members share, so two groups of the same record type that differ only by status no longer render as two visually identical cards, and a group of completed records is no longer labelled "drafts".#12089, #11217Recording the Loom Review Model walkthrough for #11217 against live UAT showed the Task Manager rendering "Complete 2 Timesheet drafts" twice. The account holds timesheet to-dos in two statuses (draft x2, complete x2); grouping keys on the composite type:wbaType:status so these are correctly two separate groups, but buildGroupTitle interpolated only the type and dropped the status. Existing unit tests split a group by wbaType but never by status, which is why the collision shipped.
2026-08-30Recorded the Loom Review Model walkthrough video for Notifications (docs/walkthroughs/issue-11218-notifications-walkthrough.mp4). Added AC requiring every scheduler-raised notification type to be enumerated in SYSTEM_GENERATED_NOTIF_TYPES, and fixed cpd_provider_unverified_followup rendering "Consultant" instead of "PPP System".#12086, #11218, #11313The walkthrough found the system-sender allowlist silently omitted a scheduler-raised type, so 14 of 17 live notifications attributed an automated message to a human role. The allowlist shape makes this failure mode recur for every new scheduled type, so the completeness requirement is now an explicit AC.
2026-08-24Adds a super-admin "Automated Emails" settings page (/settings/automated-emails) — config CRUD for a fixed 17-type email catalog (Welcome, CPD Activity Approval, CPD Provider Process, WBA x4, Feedback, Reflections, Logbook Case x2, Appraisals x4, Timesheet x2), each with an on/off toggle and editable send timing (immediate, or N minutes/hours/days after trigger). Backed by a new automated_email_template table (seeded with all 17 canonical rows) and ppp.notifications.automatedEmailTemplates.* router, all procedures adminProcedure-gated. Config only — every existing sendEmail call site is still called directly with hardcoded copy/timing; wiring a generic send pipeline to consult this table is a separate, larger follow-up.#11782, #11769Task 18 S3 (#11220 parent) — admin needs a single place to see and adjust every automated email type's on/off state and timing, ahead of a later pipeline-wiring slice that would let that config actually drive sends.
2026-08-24Renamed the Actions/Action Items page and sidebar nav label to "Task Manager" (#11767). The spec's Naming callout ("must be called 'Actions' (or 'Action Items')") is superseded — updated in place to require "Task Manager" instead, citing this PR. The /action-items route path and its legacy /inbox redirect are unchanged.#11779, #11767Task 18 S1 (#11767) unifies the previously tab-split To-do/Notifications view under a new "Task Manager" name as part of the Admin Console rework. This spec's own prose "Naming" AC directly named "Actions"/"Action Items" as the required label, so the rename is a real divergence from a stated AC, not just a UI tweak — recorded here per CLAUDE.md's "update the spec with the reason in the Change Log" rule, flagged via the code-paths glob correctly matching this PR's change to RecentActionItemsMenu.tsx and TaskMetadataBar.tsx.
2026-08-24Adds a super-admin "Notification Schedules" settings page (/settings/notification-schedule) — config CRUD for admin-authored schedules (name, active toggle, send frequency/time, audience filter by account type/speciality/hospital, message title/body, optional deep-link target). Backed by a new notification_schedule table and ppp.notifications.notificationSchedule.* router, all procedures adminProcedure-gated. Config only — no processXxxNotifications.ts processor reads it yet; wiring is a separate follow-up.#11778, #11768Task 18 S2 (#11220 parent) — admin needs a way to author scheduled-notification config (audience, timing, copy, deep-link) ahead of the processor wiring that will consume it, so the two can ship as independently reviewable slices.
2026-08-12Adds notifications.push-token.released-on-sign-out — signing out releases that device's token, scoped to (userId, token) with the caller resolved from the session so nobody can deregister another user's device. Also corrects the stale residual clause on notifications.push-token.single-owner, which still stated the sign-out deregistration half was not implemented.#11546, #11507#11491 bound a device token to one user at a time, but only ever acts on a SAVE — so it cannot help in the window where a user signs out and nobody signs in after them. The row survives, and sendPushNotification selects every row for a userId with no liveness check, so that user''s clinical content kept being delivered to a handset sitting on the login screen. Rob''s follow-up on #11507 classified this precisely: a hygiene/least-privilege gap rather than cross-user disclosure, since the device is with its own prior owner — which is why it is a separate AC rather than a correction of the one above.
2026-08-12Adds two ACs — the fortnightly timesheet submission reminder is delivered by a registered scheduled tick at all (it had none), fired every 15 minutes rather than hourly so it lands inside its 06:00-06:29 instance-timezone window in sub-hour-offset zones; and a reminder schedule that can never satisfy its own window is reported at boot rather than inferred from silence.#11478, #11104processTimesheetSubmissionReminders shipped in #4683 with NO scheduled caller — its only invocation was an admin-callable protectedProcedure, so the prompt could not fire on any instant of any day, and Matt sat on a fortnight of unsubmitted geofence drafts (ts1000/ts1001/ts1020/ts1078, all status=draft) without being prompted. This is #10942 one step worse: a disjoint tick at least fires, a missing one does not exist, and both look identical in the logs because neither writes anything. The 15-minute cadence is load bearing, not a preference — the window is evaluated in the instance timezone read from instance_config at run time (Europe/London on UK, Australia/Sydney on AU), so a cron anchored to either named zone is wrong on the other; anchoring to UTC hourly then lands at :30 past every local hour in UTC+05:30 and :45 in UTC+08:45, entirely disjoint from a minute &lt; 30 window. Every IANA offset is a multiple of 15 minutes, so */15 always lands.
2026-08-01Adds AC notifications.scheduled.idempotency-key-enforced-at-db — the shared scheduled-notification idempotency key must be enforced by a partial UNIQUE index on (user_id, (metadata-&gt;&gt;'scheduledKey')), with the insert claiming the key via an explicitly-targeted ON CONFLICT … DO NOTHING, not merely checked by a pre-insert SELECT.#11325, #11312#11311 converged both wellness generators on one dedup key, but a pre-insert SELECT is advisory — two job replicas (or one retried) can both pass it and both insert, which is UAT rows 1170/1171 (byte-identical, same millisecond). The index is keyed on user_id as well as the key because registration_recheck_summary:&lt;year&gt; is deliberately fanned out to every super admin; it is partial because event-driven notifications carry no key and legitimately recur; and the arbiter is explicitly targeted because three other unique indexes on notifications would otherwise be silently swallowed by a bare DO NOTHING.
2026-08-01Adds AC — system-generated notifications (scheduled reminders and automated prompts) render "PPP System" as their sender, never a person. The decision is made on the notification type, not on sender_id. Also re-points code-paths: at the sender-resolution files in src/utils/ and src/constants/, which no existing glob matched.#11323, #11313Matt's 1 Aug screenshot showed the same weekly wellness reminder rendering two ways in one dropdown — as "Matthew Randell" (the legacy generator wrote sender_id = user_id, so the recipient's own name came back at them as the sender) and as "Consultant" (the sender_id null role-label fallback). #11316 stopped new rows carrying a self-sender, but historical UAT rows still hold the old shape, so keying the display on type renders both correctly without a data migration.
2026-08-01Adds AC notifications.scheduled.shared-idempotency-key — when a scheduled notification can also be produced by a second, non-scheduled generator, every path must write and match the SAME metadata idempotency key. Scheduled reminders are system-generated, so senderId is null and never the recipient's own id.#11316, #11311Generalises the root cause of the duplicated weekly wellness reminder (#11311). A path that deduplicates on a key the other never writes is blind to the other's rows, so both insert once per cycle — the failure is structural and applies to any future multi-generator scheduled notification, not just wellness.
2026-07-26Gave the weekly wellness questionnaire reminder its own Europe/London-anchored cron tick (30 * * * *, WELLNESS_REMINDER_TICK) instead of riding the shared daily 20:30 UTC notification bundle, plus a boot-time self-check that logs an error if the registered schedule can never satisfy the reminder's own eligibility window.#10973, #10942, #10931The reminder is gated on Friday 06:30-06:59 Europe/London, but its only scheduled caller fired at a fixed 20:30 UTC — 21:30 BST in summer, 20:30 GMT in winter. The cron's tick set and the window's instant set were disjoint on every day of every year, so processWellnessNotifications always logged processed:0 (confirmed across UAT ContainerAppConsoleLogs_CL from 2026-06-25 onward) and the reminder only ever got created by the client-triggered fallback on app load — i.e. only if the doctor happened to open the app inside a 29-minute weekly slot. Matt's 22 Jul Notifications panel showing an 18-day-old reminder with nothing newer is that failure mode.
2026-07-25Registered two new admin-callable tRPC procedures (monitorGeofenceStreamSilence, monitorStuckOpenGeofenceShifts) in the shared routers/procedures/notifications/index.ts router, alongside the existing reconcileMissingGeofences/monitorGeofencePreferences monitors.#10916These two monitors are owned in substance by the timesheets/geofence feature (see timesheets.md's Server-side Monitoring section and its own #10916 changelog fragment) but share this router file structurally, which trips this spec's code-paths glob on routers/procedures/notifications/**. Noted here for traceability only — no notifications-domain behaviour changed.
2026-06-24Added Redis cache layer to getActionItemCount and listNotifications (20s TTL, per-userId invalidation on writes); raised frontend poll interval from 15s to 30s and disabled background-tab polling — reducing Postgres load on the hot notification endpoints.#9247, #9230Issue #9230 (sub-second page loads, #9227): notification poll endpoints were the highest-frequency Postgres queries. Caching with write-side invalidation means users always see fresh data on their next poll while eliminating redundant DB hits from background tabs. The PppCache fire-and-catch pattern ensures graceful degradation if Redis is unavailable (falls through to Postgres as before).
2026-06-21Closed a userId mass-assignment hole in notifications.update — the update payload is now whitelisted to mutable columns (isRead/message/type/metadata/updatedBy) and UpdateNotificationSchema omits userId/senderId/recordId/createdBy, so a caller can no longer transplant a notification onto another user.#8999, #8990Security follow-up to #8995. The IDOR WHERE-clause fix alone left ownership-transfer possible because .set(params) spread the settable userId FK; this adds defence-in-depth (schema omit + service-layer whitelist) and a regression test.
2026-06-21Scope notifications.update to the caller's own notification (IDOR fix) — no-email context now throws UNAUTHORIZED before touching the database.#8995, #8990updateNotification ran UPDATE ... WHERE id = $id with no userId scope, allowing any authenticated user to modify another user's notification. Fixed by adding eq(notifications.userId, user.id) to the WHERE clause.
2026-06-20Decouple bell-open seen-pill from per-row read-bar — add seenAt column, markAllSeen mutation, and update badge count to use seenAt IS NULL.#8987, #8978Bell-open and per-row click previously shared isRead, making it impossible to clear the red badge without also marking every notification as read. Adding a seenAt timestamp lets opening the bell silence the pill while leaving each row's blue bar intact until the user explicitly clicks through (#8978, sub-2 of #8942).
2026-06-20"View all notifications" navigates directly to /action-items?tab=notifications instead of via the /notifications redirect.#8980, #8942The redirect hop added a spurious history entry that caused the Action Items page to render inside the current WebView frame on mobile, overlaying the Home screen instead of transitioning cleanly. Removing the hop makes navigation single-step and fixes the overlay-on-Home effect reported in #8942 (sub-item 4, web-side).
2026-06-09The annual registration re-check scheduled job (scheduledNotificationService) now persists each registration's verified status and last-checked date back to the row, in addition to sending notifications.#8412, #8327The once-a-year re-check job in scheduledNotificationService only sent notifications and never wrote the verification outcome back, so an inconclusive lookup left a registration "Unverified" forever. The job is now the authoritative source of truth for registration verification state.
2026-05-19Per-category notification opt-out UI shipped — Notifications → Settings tab with togglable proactive reminder categories; server gates createNotification against the user's disabledTypes; transactional notifications stay mandatory.#6501, #4979Users had no way to opt out of individual notification categories (e.g. wellness reminders) while keeping CPD reminders. Resolves Q1 of #4979 per the resolved opt-out matrix.
2026-05-19Drift re-baseline — #5026 (WBA assessor email) marked built after close; 4 @wip BDD scenarios added for #4974, #4980, #4979; status remains in-progress#5346, #5026, #4974, #4980, #4979Spec was out of sync with closed issue #5026 and lacked BDD coverage for the 3 remaining open bugs/enhancements.
2026-05-05Awaiting-Matt sweep — Q1 (#4979 per-category opt-out matrix) resolved engineering-led. 11-row matrix: transactional + compliance reminders mandatory; proactive nudges + marketing opt-out; email channel independently togglable from in-app. Status flipped to Specified.#4979Engineering can specify the opt-out matrix with industry conventions; defers no information that requires Matt's commercial judgement.
Mar 2026To-Do tab + work queue unified#3607, #3608, #3673, #3685All outstanding items now in one place
Mar 2026CPD and profile completion prompts built#3606, #3678, #3687, #3689Proactive nudge to drive engagement
Mar 2026Proactive nudges dashboard banners — CPD hours + plan not submitted (#3609)#4302Dashboard banners chosen over notification bell for phase 1; dismissible, per-user localStorage persistence. Spec note: long-term vision is bell integration (#3611).
Mar 2026"Inbox" renamed back to "Actions"#3953"Inbox" causes email association — confuses users
Jan 2026Unified actions concept identified from walk-throughWalk-through notesBell should be single source of truth for all reminders
2026-04-22Drift re-baseline — 5 ACs added, 5 issues triaged, conflict markers cleaned#5346, #5026, #4980, #4979, #4974, #4824See audit .drift-audits/notifications.md; Matt Q1 flagged for #4979 scope expansion
Sources & Recordings ​
SourceNotes
https://drive.google.com/file/d/1HDF4acVA0QKImQ29Wu0rp_kVIgb-VGFVg_XwcZnUV6EDescription pending SGD audit
https://docs.google.com/document/d/1YhgQSFL9iOlQLoTrQYSwxRNXH4Dg4wefkItcwljQZmoDescription pending SGD audit

Internal documentation — org members only