Notification BLoC
Component Detail
Description
BLoC managing all notification centre state including the feed list, unread count, active filters, and real-time update events. Subscribes to Supabase Realtime on init and processes incoming notification events into state updates. Handles mark-read, mark-all-read, and clear-all business operations.
notification-bloc
Summaries
The Notification BLoC is the central engine powering the app's real-time notification experience, directly driving user engagement and retention. By delivering instant, role-appropriate alerts without manual refresh, it reduces the risk of users missing critical assignments, certificates, or peer mentor updates — events that directly affect operational outcomes and satisfaction scores. This component underpins trust in the platform: users who see timely notifications are more likely to act on them, increasing overall platform utilisation and reducing support overhead from missed deadlines or overlooked tasks. Its built-in unread count and filter state management ensure coordinators and admins can prioritise their workload efficiently, translating to faster response times and better programme outcomes.
The Notification BLoC is a high-complexity component with broad delivery implications. It depends on three other components — the notification repository, the role-aware filter service, and the Supabase Realtime subscription service — meaning those must reach stability before this component can be fully integrated and tested. Real-time subscription logic introduces non-trivial testing requirements: unit tests alone are insufficient, and integration tests against a live or emulated Supabase instance are required. The optimistic update and rollback paths add additional QA surface area.
Plan for at least one dedicated sprint for end-to-end testing. Connection lifecycle (init/close) and background reconnection scenarios should be explicitly scoped into the test plan to avoid late-stage regressions.
Notification BLoC is implemented using the flutter_bloc pattern, exposing a mapEventToState transformer that processes NotificationEvent subtypes — load, mark-read, mark-all-read, clear-all, apply-filter, and realtime-event. On init, it subscribes to Supabase Realtime via supabase-realtime-subscription-service, routing INSERT payloads through onRealtimeEvent() which converts raw NotificationPayload objects into PrependNotification state transitions. Role-aware filtering is delegated entirely to role-aware-notification-filter, keeping business rules out of the BLoC. The stream: Stream
The close() method must cancel the Realtime subscription to prevent memory leaks. State shape includes the feed list, filter, sort, and unread count. Pagination is managed via loadNotifications with userId and UserRole arguments forwarded to the repository.
Responsibilities
- Maintain notification feed list with filter and sort state
- Track and expose unread notification count
- Process Supabase Realtime INSERT events for new notifications
- Handle mark-as-read, mark-all-read, and clear-all commands
- Apply role-aware filtering based on current user role
Interfaces
mapEventToState(NotificationEvent)
add(NotificationEvent)
stream: Stream<NotificationState>
loadNotifications(String userId, UserRole role)
markAsRead(String notificationId)
markAllAsRead()
clearAll()
applyFilter(NotificationFilter)
onRealtimeEvent(NotificationPayload)
close()
Relationships
Dependencies (3)
Components this component depends on
Dependents (4)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component