Dismiss Alert

Feature Owner : Joylynne Esportuno
Module : User Management and Enrollment
Priority : P4
Sprint #6 : Fully Implemented
Date : July 2, 2026

EXECUTIVE SUMMARY

What is this feature ?
Dismiss Alert marks notifications as read and decreases the unread badge count.

Why does it matter ?
Users need a clean notification center that reflects what they have already seen.

What's the MVP scope ?
Mark a single notification read from the bell or notification click. Delete and realtime sync are out of scope.

1. USER PAIN POINT & SOLUTION

Without Dismiss Alert

Unread badges can remain noisy if users cannot clear alerts.

Pain Point

Emotional : Notification clutter causes anxiety.
Functional : Users cannot distinguish new vs handled items.
Business Impact : Alerts lose trust.

Current State (Already implemented)

Users mark alerts read and unread count updates immediately.

Marketing Hook

"Keep notifications accurate and actionable."

2. 4D FRAMEWORK MAPPING

Diagnose

Shows which alerts still need attention.

Design

Keeps read/unread status in notification UX.

Develop

Updates notifications.is_read and read_at.

Deliver

Improves daily alert workflow.

3. USER FLOWS

Entry Point

Notification bell.

Success Criteria

Notification read state persists and badge count decreases.

Main Flow

1. User opens notification bell.

2. User clicks notification or Mark as Read.

3. UI optimistically marks read.

4. API persists read state.

5. Badge count updates.

Edge Cases

• No data : Empty notification state

• API error : Roll back unread state

• Permission denied : Do not update notification owned by another user

Decision Points

• IF API succeeds, keep read state

• ELSE restore unread state

4. INFORMATION ARCHITECTURE

Primary Information

• Notification title/body

• Read/unread status

• Unread count

Secondary Information

• Timestamp

• Link

Tertiary Information

• Type metadata

Actions

Primary CTA : Mark as Read
Secondary Actions : Open notification, delete where available

5. WIREFRAMES

Excluded — Feature fully implemented.

6. WIREFLOWS

Excluded — Feature fully implemented.

7. PROTOTYPE

Excluded — Feature fully implemented.

8. BACKEND SCHEMA

Database Tables

• notifications.id

• notifications.to_user_id

• notifications.is_read

• notifications.read_at

Constraints

• Only the notification recipient can mark the notification read

• Mark-read must not delete the notification record

9. API ENDPOINTS

Endpoint 1: PATCH /api/notifications/update-notifications

Purpose: Marks one notification as read.
Auth: Authenticated notification owner.
Request Body: Notification ID.
Response Data: Success state and updated notification fields where applicable.

Endpoint 2: GET /api/notifications/get-notifications

Purpose: Loads notification list and unread state used by the bell.
Auth: Authenticated user.
Frontend Use: Reconcile local unread count after refresh.

10. DATA REQUIREMENTS

Frontend Needs

• Notification ID

• is_read boolean

• read_at timestamp when available

• Current unread count

• Notification link/type for click behavior

• Optimistic update and rollback state

Backend Needs

• Authenticated user ID

• Notification ID from request

• Recipient ownership check through to_user_id

API Calls Frontend Will Make

• Load notifications

• Mark one notification read

Caching Strategy

• Unread counts should be derived from the current notification state. Avoid relying on stale cached counts after mark-read actions.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

• Mark-read update should filter by both notification ID and recipient user ID. Notification list should be paginated or limited for large accounts.

Client Optimization

• Use optimistic update for immediate feedback, then rollback on failure. Avoid refetching the entire notification list after every read action unless necessary.

Caching Strategy

• Keep a local notification list for the bell session. Reconcile with server polling/manual refresh.

API Response Time

• Mark-read should complete quickly because it updates a single row. Target a sub-second interaction feel.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

• Authenticated User: Can mark their own notifications read

• Unauthenticated User: No access

13. ERROR HANDLING

Current Existing Error Handling

• PATCH /api/notifications/update-notifications authenticates the user before any update.

• It returns badRequest("Invalid request body") when request JSON cannot be parsed.

• It validates the body with markNotificationReadSchema and returns validationError("Invalid notification ID") with flattened field errors when invalid.

• The Supabase update filters by both id and to_user_id, so users can only mark their own notifications as read.

• Database update errors are logged as [update-notifications] Database error: and return internalError("Failed to update notification").

• If the update returns no rows, the route returns notFound("Notification not found or you do not have permission to update it").

• Unexpected failures are logged as [update-notifications] Unexpected error: and returned through ApiResponseHelper.handleError(error, "Failed to update notifications").

14. TESTING CHECKLIST

Happy Path

• Mark read button works.

• Clicking notification marks read.

• Badge decreases.

• Refresh keeps read state.

Edge Cases

• Unauthorized update blocked.

• API failure rolls back UI.

• Invalid notification ID returns validation error.

• Already-read notification does not increase/decrease badge incorrectly.

15. OPEN QUESTIONS

For Frontend:

N/A

For Backend:

N/A

16. OUT OF SCOPE

• Realtime notification sync and analytics events.

17. SUCCESS METRICS

• Unread count accuracy

• Notification interaction rate

18. DEPENDENCIES

This feature depends on:

• Notifications table

• Notification bell component

• Auth helper and notification ownership checks

These features depend on this:

• Review Alert unread badge behavior

• View Feedback notification click behavior

• General notification center usability

19. TIMELINE & OWNERSHIP

Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Uriel Tribiana
Estimated Completion: Fully implemented