Real-Time In-App Notifications

[ohamamarachi474-del]

Layer: Full Stack (Frontend UI + Backend WebSocket/DB)
Effort: Medium (4–6h)

Users need to receive instant updates when critical lifecycle events occur (e.g., an artisan accepts a booking, or a client releases a payment) without needing to manually refresh their browser.

Required Changes

1. Database & Persistence

• Create a Notification database schema to store alerts persistently (fields: user_id, type, message, is_read, created_at, reference_id).
• This ensures users don't miss notifications if they happen to be offline when the event is triggered.

2. Backend Real-Time Gateway (FastAPI)

• Implement a WebSocket endpoint (e.g., ws://api/v1/notifications/stream) that authenticated users can connect to upon logging in.
• Hook into the existing Booking and Payment service layers to push JSON payloads to the WebSocket manager whenever the following events occur:
  • Booking Accepted / Cancelled
  • Bid/Pitch Received
  • Escrow Payment Released / Refunded

3. Frontend UI (Next.js)

• Navbar Bell: Add a notification bell icon to the global Navbar featuring a dynamic "unread count" badge (e.g., a red circle with a number).
• Notification Dropdown: Clicking the bell should open a dropdown listing the last 5-10 notifications, with distinct styling for unread vs. read messages. Clicking a notification should mark it as read via API and redirect the user to the relevant booking/payment page.
• Toast Alerts: Whenever a WebSocket message is actively received while the user is online, trigger an immediate UI Toast alert (using sonner or radix-ui/react-toast) in the corner of the screen.

---

Acceptance Criteria

• Notification table is created and hooked into core backend state changes.
• Authenticated users successfully establish a stable WebSocket connection on page load.
• Navbar bell displays an accurate, live-updating unread count.
• Clicking the bell reveals a dropdown of recent notifications; clicking an item marks it as read and navigates to the correct page.
• Crucial events trigger non-intrusive toast pop-ups globally across the application.
• Disconnections are handled gracefully (the WebSocket automatically attempts to reconnect without crashing the app).

[Mystery-CLI]

I have read through the required implementations and understand what to do can i work on it?

[fadee26]

Hello maintainer, please can i take up this issue

[grantfox-oss]

🦊 GrantFox — @fadee26 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #298)
2. Your PR will be reviewed by the stemscreatives maintainers

Good luck! Track your progress on GrantFox.

[ohamamarachi474-del]

@fadee26 please whats the update

[fadee26]

You will get PR shorlty