[TTAHUB-5539] Specification for actionable notification backend by thewatermethod · Pull Request #3661 · HHS/Head-Start-TTADP

thewatermethod · 2026-05-29T18:20:51Z

Description of change

Design backend for actionable notifications. Frontend tickets are briefly listed but work will be broken down separately.

How to test

Review implementation proposal. Identify additional work that may need to be completed. Ask questions where specification is unclear.

Issue(s)

https://jira.acf.gov/browse/TTAHUB-5339

Checklists

Every PR

Before merge to main

OHS demo complete
Ready to create production PR

Production Deploy

PR created as Draft
Staging smoke test completed
PR transitioned to Open (this ready_for_review transition triggers the Slack/Jira automation)
Reviewer added after the PR is Open (elainaparrish is the authorized approver under normal circumstances)
- Sequence: Draft PR → Smoke test → Open PR (automation runs) → Add reviewer
- Confirm that the Slack notification was sent after the PR was opened
- Confirm that linked Jira ticket(s) transitioned as expected; if not, review the GitHub Actions workflow logs

After merge/deploy

Update JIRA ticket status

Copilot

Pull request overview

This PR adds a backend design specification for actionable notifications, outlining proposed data modeling, services, scopes, handlers, scheduled cleanup, email-notification simplification, and related frontend follow-up work.

Changes:

Adds a new specs/actionable-notifications/index.md design document.
Defines proposed notification schema, configuration, service APIs, scopes, and handler responsibilities.
Lists planned backend tickets plus frontend follow-up areas.

Impact Assessment:

Benefits: Medium — provides a shared implementation plan for a cross-cutting notification system.
Risks: Medium — unresolved schema and cleanup-query issues could lead to implementation mistakes if copied directly.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

AdamAdHocTeam

I think this looks good. Should we mention something about cleaning up no longer valid notifications. For example two approvers added to report and submitted. Then the report is moved back to needs action?

Overall good start (minor comments)

github-actions · 2026-06-01T16:31:38Z

⚠️ Diff size advisory: This PR is 3525 lines (3460+, 65−), exceeding the 500-line guideline. Consider splitting into smaller changes.

github-actions · 2026-06-01T16:31:38Z

⚠️ Review count advisory: 1 of 2 required human approvals. 1 more needed. Current approvers: AdamAdHocTeam.

thewatermethod · 2026-06-01T16:51:08Z

I think this looks good. Should we mention something about cleaning up no longer valid notifications. For example two approvers added to report and submitted. Then the report is moved back to needs action?

@AdamAdHocTeam good call, I updated to add a new service type

kryswisnaskas

Adding four inline review findings from Codex.

* feat: add Notifications schema (model, migrations, seed, tests) - Add NOTIFICATION_TYPES and actionable_notifications feature flag to constants - Create Notifications table migration with all spec columns including archivedAt/viewedAt (DATEONLY) - Add actionable_notifications to enum_Users_flags migration - Create Notification Sequelize model with User association - Add User.hasMany(Notification) association - Add seed data with user-specific and global notifications - Add model tests (8 passing) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Simplify model * Update to add "triggeredAt" to model * Add all enum types * Remove digest from notifications enum * Update model with other needed field --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat: add Notifications schema (model, migrations, seed, tests) - Add NOTIFICATION_TYPES and actionable_notifications feature flag to constants - Create Notifications table migration with all spec columns including archivedAt/viewedAt (DATEONLY) - Add actionable_notifications to enum_Users_flags migration - Create Notification Sequelize model with User association - Add User.hasMany(Notification) association - Add seed data with user-specific and global notifications - Add model tests (8 passing) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Simplify model * Update to add "triggeredAt" to model * Add all enum types * Scopes, work in progress * Remove digest from notifications enum * Add notification scopes * Register scopes * Fix bugs, add integration test * Update model with other needed field --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…le-notification-spec

* feat: add Notifications schema (model, migrations, seed, tests) - Add NOTIFICATION_TYPES and actionable_notifications feature flag to constants - Create Notifications table migration with all spec columns including archivedAt/viewedAt (DATEONLY) - Add actionable_notifications to enum_Users_flags migration - Create Notification Sequelize model with User association - Add User.hasMany(Notification) association - Add seed data with user-specific and global notifications - Add model tests (8 passing) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Simplify model * Update to add "triggeredAt" to model * Add all enum types * Scopes, work in progress * Remove digest from notifications enum * Add notification scopes * Register scopes * Fix bugs, add integration test * Add services and tests * Update model with other needed field * Accomodate missing column in services * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Add notification configuration tests * fix: replace generic deleteNotification(scopes) with targeted delete helpers - deleteNotification(notificationId) now accepts a single ID, throws when falsy — eliminates the empty-scopes full-table-delete risk - adds deleteNotificationsByEntityAndType(entityId, notificationType) for event-driven stale-notification cleanup; throws when either arg is falsy - updates and expands tests to cover both new signatures and their guards - updates spec doc with typed signatures and safety-guard notes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix bad test * [TTAHUB-5387] Add notification handlers (#3674) * fix: cap getNotifications limit at 100 and add comprehensive tests - Fix Math.max -> Math.min bug in getNotifications limit calculation - Add handler unit tests (src/routes/notifications/handlers.test.ts) - Add policy unit tests (src/policies/notifications.test.ts) - Fix and expand service tests for sort field/direction validation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add param middleware * Updates from code review * refactor: separate per-user notification state into NotificationUserStates table The Notifications table previously stored viewedAt and archivedAt directly on the notification row. Global notifications (userId=null) could not track whether different users had independently viewed or archived them — a single row cannot hold state for multiple users. Changes: - Migration: creates NotificationUserStates (notificationId, userId, viewedAt, archivedAt, UNIQUE on notificationId+userId with FK cascades), backfills existing per-user state, and drops viewedAt/archivedAt from Notifications - New model: NotificationUserState with belongsTo Notification+User - Notification model: removed archivedAt/viewedAt/isInformational, added hasMany(NotificationUserState, { as: 'userStates' }) - Service: updateNotification → updateNotificationState(notificationId, userId, { viewedAt?, archivedAt? }) — upserts per-user state row; getNotifications(userId, scopes, options) — LEFT JOINs state, filters archived, returns NotificationWithState[] - Types: added NotificationUserStateModel and NotificationWithState - Policy: added isGlobalNotification(); canUpdateNotification() now allows admin, owner, or global notification (any user can set their own state) - Handlers: getNotificationsHandler passes userId as first arg; updateNotificationHandler calls updateNotificationState - Spec: updated to document new table, service signatures, cleanup logic - Tests: 121/121 passing across 10 suites Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update to remove findOrCreate * Update seeder * Define relation in both directions * Update test * Map scopes to types directly to prevent drift * Updates from code review --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Regenerate Logical Data Model * Condense down notifications table * Remove extraneous migration * Fix LDM bugs * Remove extra columns from migration --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…able-notification-spec

github-actions · 2026-06-09T15:55:20Z

📊 Review Metrics

Auto-generated by the PR Review Metrics workflow. Observe-only — no action required.

Metric	Value
PR Status	✅ Merged
Reviewer Count	2
Reviewers	@AdamAdHocTeam, @kryswisnaskas
First-Review Turnaround	68.7 hr
Total Review Events	7

Review Timeline

State	Reviewer	Submitted At
💬 COMMENTED	@AdamAdHocTeam	2026-06-01 15:22 UTC
💬 COMMENTED	@AdamAdHocTeam	2026-06-01 15:23 UTC
💬 COMMENTED	@AdamAdHocTeam	2026-06-01 15:51 UTC
✅ APPROVED	@AdamAdHocTeam	2026-06-01 15:52 UTC
💬 COMMENTED	@AdamAdHocTeam	2026-06-01 15:53 UTC
💬 COMMENTED	@kryswisnaskas	2026-06-03 15:19 UTC
💬 COMMENTED	@kryswisnaskas	2026-06-03 16:16 UTC

thewatermethod added 2 commits May 29, 2026 14:16

Add actionble notification specification

c2b9b3f

Remove dead link

4c82cb4

thewatermethod marked this pull request as ready for review May 29, 2026 18:41

Copilot AI review requested due to automatic review settings May 29, 2026 18:41

Copilot started reviewing on behalf of thewatermethod May 29, 2026 18:41 View session

thewatermethod requested review from AdamAdHocTeam, Andrew565, hardwarehuman, kryswisnaskas and tommaroh May 29, 2026 18:41

Copilot AI reviewed May 29, 2026

View reviewed changes

Comment thread specs/actionable-notifications/index.md Outdated

Comment thread specs/actionable-notifications/index.md Outdated

thewatermethod and others added 2 commits June 1, 2026 09:04

Potential fix for pull request finding

f870875

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

ee4a14d

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

thewatermethod changed the title ~~[TTAHUB-5539] Add specification for actionable notification backend~~ [TTAHUB-5539] Specification for actionable notification backend Jun 1, 2026

thewatermethod added 2 commits June 1, 2026 09:06

Update index.md

750557c

Merge branch 'main' into mb/TTAHUB-5539/actionable-notification-spec

59a215a

AdamAdHocTeam reviewed Jun 1, 2026

View reviewed changes

Comment thread specs/actionable-notifications/index.md

AdamAdHocTeam reviewed Jun 1, 2026

View reviewed changes

Comment thread specs/actionable-notifications/index.md Outdated

AdamAdHocTeam reviewed Jun 1, 2026

View reviewed changes

Comment thread specs/actionable-notifications/index.md Outdated

AdamAdHocTeam approved these changes Jun 1, 2026

View reviewed changes

Update index.md

af4b188

thewatermethod added 3 commits June 1, 2026 12:33

Update index.md

5f6740a

Update spec

b329d37

Add new subsection

6782675

thewatermethod added 2 commits June 1, 2026 13:33

Update spec

ef417d6

Correct spelling mistake

1a37880

kryswisnaskas reviewed Jun 3, 2026

View reviewed changes

Comment thread specs/actionable-notifications/index.md

Comment thread specs/actionable-notifications/index.md

Comment thread specs/actionable-notifications/index.md Outdated

Comment thread specs/actionable-notifications/index.md

thewatermethod and others added 11 commits June 4, 2026 13:49

Update spec

f7a4c6a

Update delete spec

7cb72bb

Merge remote-tracking branch origin/main into mb/TTAHUB-5539/actionab…

d50e22c

…le-notification-spec

Rename migration

7bdf704

Rename seeder

1105f61

Add feature flag migration to notifications table

c052c3c

Fix LDM + missed import

9aa7905

Merge remote-tracking branch 'origin/main' into mb/TTAHUB-5539/action…

b0955cf

…able-notification-spec

thewatermethod enabled auto-merge June 9, 2026 14:30

thewatermethod added this pull request to the merge queue Jun 9, 2026

Merged via the queue into main with commit 68aa759 Jun 9, 2026
14 checks passed

thewatermethod deleted the mb/TTAHUB-5539/actionable-notification-spec branch June 9, 2026 15:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[TTAHUB-5539] Specification for actionable notification backend#3661

[TTAHUB-5539] Specification for actionable notification backend#3661
thewatermethod merged 23 commits into
mainfrom
mb/TTAHUB-5539/actionable-notification-spec

thewatermethod commented May 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AdamAdHocTeam left a comment

Uh oh!

github-actions Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

thewatermethod commented Jun 1, 2026

Uh oh!

kryswisnaskas left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

thewatermethod commented May 29, 2026

Description of change

How to test

Issue(s)

Checklists

Every PR

Before merge to main

Production Deploy

After merge/deploy

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AdamAdHocTeam left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thewatermethod commented Jun 1, 2026

Uh oh!

kryswisnaskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 9, 2026

📊 Review Metrics

Review Timeline

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Jun 1, 2026 •

edited

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading