Notifications

​

Overview

​

Accessing Notifications

​

Notification Bell Icon

1. Look for the bell icon (🔔) in the navbar
2. A red badge shows the number of unread notifications
3. Click the bell icon to open the notifications modal

​

Notification Modal

• All notifications for your household
• Grouped by notification type
• Ordered by creation date (most recent first)
• Unread notifications marked with an “Unread” badge

​

Notification Types

​

Common Notification Categories

• Bills: New bills added, bills marked as paid, upcoming due dates
• Chores: New chores created, chores completed, overdue chores
• Shopping: Items added to shopping list, items marked as purchased
• Maintenance: New maintenance tasks, tasks completed, scheduled maintenance
• Household: New members invited, role changes, member activity

​

Notification Structure

• Title: Brief summary of the activity
• Body: Detailed description or context
• Type: Category of the notification
• Timestamp: When the notification was created
• Read Status: Whether you’ve viewed the notification

​

Managing Notifications

​

Viewing a Notification

1. Open the notifications modal by clicking the bell icon
2. Browse through the notification list
3. Hover over a notification to highlight it
4. Click on any notification to dismiss it

​

Dismissing Individual Notifications

1. Open the notifications modal
2. Click on the notification you want to dismiss
3. The notification is immediately deleted
4. The unread count updates automatically

// Clicking a notification dismisses it
// See: src/components/modals/NotificationsModal.tsx:59
await fetch("/api/notifications/delete", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ id }),
});

​

Mark All as Read

1. Open the notifications modal
2. Scroll to the bottom of the modal
3. Click the Mark All as Read button
4. All notifications are marked as read
5. The modal closes automatically

​

Empty Notification State

• The modal displays: “No notifications yet.”
• The notification badge disappears from the bell icon
• This indicates you’re up-to-date with all household activity

​

Notification Behavior

​

Real-Time Updates

• New notifications appear when household activity occurs
• The unread count updates automatically
• Opening the modal refreshes the notification list

​

Persistence

• Your notifications remain available after logging out
• Notifications are tied to your household, not your session
• All household members see notifications relevant to shared activities

​

Household-Wide Notifications

• All members see the same household notifications
• No role-based filtering (owners, members, and guests see all notifications)
• This keeps everyone informed about household activities

​

API Endpoints

​

Fetching Notifications

GET /api/notifications

• Array of notification objects
• Ordered by creation date (descending)
• Filtered by your household ID

​

Deleting a Notification

POST /api/notifications/delete
Body: { id: "notification-id" }

• Removes the notification from the database
• Updates the unread count

​

Clearing All Notifications

POST /api/notifications/clear

• Marks all household notifications as read
• Resets the unread count to zero

​

Creating Notifications

​

Notification Creation Parameters

interface NotificationPayload {
  householdId: string;  // The household to notify
  type: string;         // Category of notification
  title: string;        // Brief summary
  body: string;         // Detailed description
}

​

Example Use Cases

• New bill added: “Electric Bill added” / “Due on Jan 15, $120.00”
• Chore completed: “Kitchen Cleaning completed” / “Completed by John”
• Member joined: “New member joined” / “Sarah accepted invitation”
• Role changed: “Role updated” / “Mike promoted to Owner”

​

Notification Settings

​

Current Behavior

• Enabled by default
• Shown to all household members
• Not customizable per user

​

Future Enhancements

• Email notifications
• Push notifications (PWA support)
• Notification preferences per user
• Notification muting or filtering
• Custom notification triggers

​

Troubleshooting

​

Notifications Not Appearing

• You’re a member of an active household
• Your household has recent activity
• You’ve refreshed the page or reopened the modal

• Try clicking the notification bell to refresh
• Navigate to another page and back to trigger a refresh
• Check the browser console for any error messages

​

Unread Count Not Updating

• The count is calculated based on the read field in the database
• Marking notifications as read updates this field

• Click “Mark All as Read” to reset the counter
• Dismiss individual notifications to reduce the count
• Refresh the page to recalculate the count

​

Modal Not Opening

1. Ensure you’re signed in
2. Check that JavaScript is enabled in your browser
3. Try refreshing the page
4. Clear your browser cache if issues persist

​

Best Practices

​

Keeping Your Feed Clean

• Regularly dismiss notifications you’ve acted on
• Use “Mark All as Read” periodically to clear old notifications
• Check notifications daily to stay updated on household activities

​

Notification Etiquette

• Respond to important notifications promptly
• Use notifications as a communication tool with household members
• Don’t ignore overdue or urgent notifications

​

Performance

• The notification system fetches data on demand
• Opening the modal triggers a fresh data fetch
• This ensures you always see the latest notifications

​

Technical Details

​

Data Model

interface Notification {
  id: string;
  householdId: string;
  type: string;
  title: string;
  body: string;
  read: boolean;
  createdAt: string;
}

​

Frontend Implementation

• Component: src/components/modals/NotificationsModal.tsx
• Navbar Integration: src/components/layout/Navbar.tsx:86
• API Integration: src/app/api/notifications/route.ts

​

State Management

• Locally within the NotificationsModal component
• Unread count tracked in the Navbar component
• Fetched on-demand when needed

​

Grouping Logic

// src/components/modals/NotificationsModal.tsx:57
const groupedNotifications = groupBy(notifications, "type");