> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traza.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

# In-App Notifications System

## Overview

The in-app notifications system will keep users informed about important events and activities within the application. This document outlines the structure, components, and considerations for implementing this feature.

## Notification Types

### Event Categories

1. Booking Related

   * New booking request received
   * Booking status changes (accepted, declined, canceled)
   * Booking reminder (upcoming appointments)
   * Payment received for booking

2. Messaging Related

   * New message received
   * Unread message reminders

3. Client Related

   * New client relationship established
   * Client profile updates
   * Client anniversary reminders

4. System Related
   * System messages (e.g., maintenance, updates)
   * Notifications for new features or updates

## Database Structure

### Notifications Collection

```typescript theme={null}
interface Notification {
  id: string;
  userId: string; // ID of user receiving notification
  type: NotificationTypeEnum; // Enum of notification types
  // Data type depends on NotificationType
  data?: {
    // Additional contextual data
    bookingId?: string;
    clientId?: string;
    messageId?: string;
    fromUserId?: string; // ID of user sending notification
  };
  isRead: boolean;
  createdAt: number; // Timestamp
  expiresAt?: number; // Optional expiration
}
```

## Components Required

1. Notification Center

   * Notification bell icon with unread count
   * Dropdown/modal for displaying notifications
   * Mark as read functionality
   * Clear all option
   * Infinite scroll for older notifications

2. Individual Notification Component
   * Display notification content
   * Action buttons based on type
   * Read/unread status
   * Timestamp
   * Click handling to navigate to relevant page

## Implementation Considerations

### Firebase Setup

1. Security Rules

   * Users should only access their own notifications
   * Implement proper indexing for queries
   * Consider rate limiting for notification creation

2. Real-time Updates
   * Use Firebase Real-time Database or Firestore listeners
   * Implement efficient querying with pagination
   * Handle offline capabilities

### Frontend Implementation

1. State Management

   * Track unread notifications count
   * Cache recent notifications
   * Handle real-time updates efficiently

2. Performance

   * Implement pagination
   * Lazy loading for older notifications
   * Optimize re-renders
   * Handle background/foreground state

3. User Experience
   * Sound/vibration options
   * Browser notifications integration
   * Do not disturb settings
   * Notification preferences

### API Endpoints Needed

1. Notification Management
   * GET /api/notifications - Fetch user's notifications
   * POST /api/notifications/mark-read - Mark notifications as read
   * DELETE /api/notifications - Clear notifications
   * GET /api/notifications/preferences - Get user notification settings
   * PUT /api/notifications/preferences - Update notification settings

### Background Processing

1. Notification Creation

   * Create notifications in response to events
   * Handle batch notifications
   * Implement retry mechanism for failed notifications

2. Cleanup
   * Archive old notifications
   * Delete expired notifications
   * Maintain notification limits per user

## Testing Considerations

1. Unit Tests

   * Notification creation logic
   * Reading/marking notifications
   * Preference management

2. Integration Tests

   * Real-time updates
   * Multiple device synchronization
   * Offline behavior

3. Performance Tests
   * Large notification sets
   * Concurrent notifications
   * Real-time update performance

## Future Enhancements

1. Push Notifications

   * Mobile push notifications
   * Web push notifications
   * Email notifications integration

2. Advanced Features
   * Notification categories/filtering
   * Custom notification sounds
   * Rich media in notifications
   * Scheduled notifications
   * Notification templates

## Monitoring and Analytics

1. Metrics to Track

   * Notification delivery success rate
   * Read rates
   * User engagement with notifications
   * Performance metrics
   * Error rates

2. Logging
   * Error logging
   * User interaction logging
   * Performance logging

## Implementation Phases

### Phase 1: Core Features

1. Basic notification structure
2. Real-time notifications display
3. Mark as read functionality
4. Basic notification center UI

### Phase 2: Enhanced Features

1. User preferences
2. Advanced filtering
3. Rich media support
4. Notification analytics

### Phase 3: Extended Features

1. Push notifications
2. Email integration
3. Advanced templating
4. Custom notification rules

## UI Organization & Filtering

### Category Tabs

The notification center will organize notifications into distinct categories with tabs:

1. All - Shows all notifications
2. Bookings - Booking-related notifications
3. Conversations - Message-related notifications
4. Other - System updates and miscellaneous notifications

### Implementation Details

1. Category Mapping (Frontend Only)

```typescript theme={null}
enum NotificationTypeEnum {
  BOOKING_REQUEST = "BOOKING_REQUEST",
  BOOKING_CANCELLED = "BOOKING_CANCELLED",
  BOOKING_PAID = "BOOKING_PAID",
  SYSTEM_UPDATE = "SYSTEM_UPDATE",
}

interface NotificationTypeConfig {
  id: NotificationTypeEnum;
  category: "booking" | "conversation" | "other";
  template: string;
  icon?: string;
}

const NOTIFICATION_CONFIG: Record<
  NotificationTypeEnum,
  NotificationTypeConfig
> = {
  BOOKING_REQUEST: {
    id: NotificationTypeEnum.BOOKING_REQUEST,
    category: "booking",
    template: "New booking request by {userName}",
  },
  BOOKING_CANCELLED: {
    id: NotificationTypeEnum.BOOKING_CANCELLED,
    category: "booking",
    template: "{userName} has cancelled a booking",
  },
  BOOKING_PAID: {
    id: NotificationTypeEnum.BOOKING_PAID,
    category: "booking",
    template: "{userName} has paid a deposit",
  },
  SYSTEM_UPDATE: {
    id: NotificationTypeEnum.SYSTEM_UPDATE,
    category: "other",
    template: "Brand new features available for artists",
  },
};

// Frontend filtering logic
const filterNotificationsByCategory = (
  notifications: Notification[],
  category?: string,
) => {
  if (!category || category === "all") {
    return notifications;
  }
  return notifications.filter(
    (notification) =>
      NOTIFICATION_CONFIG[notification.type].category === category,
  );
};

// Simplified database model
interface Notification {
  id: string;
  userId: string;
  type: NotificationTypeEnum;
  data?: Record<string, any>;
  isRead: boolean;
  createdAt: number;
}

// Simplified database query (no category filtering needed)
const getNotifications = async (userId: string) => {
  return db
    .collection("notifications")
    .where("userId", "==", userId)
    .orderBy("createdAt", "desc")
    .limit(20)
    .get();
};
```

This approach:

* Keeps the notification data model simple
* Makes category management flexible
* Allows for easy reorganization of notifications into different categories
* Reduces database complexity and query overhead
* Enables quick updates to notification organization without backend changes

Note: If we need analytics on notification categories later, we can derive that from the notification types rather than storing the category directly.

2. UI Components Structure

```typescript theme={null}
interface NotificationCenterProps {
  notifications: Notification[];
  activeTab: NotificationCategory | "all";
  onTabChange: (tab: NotificationCategory | "all") => void;
}

interface NotificationListProps {
  notifications: Notification[];
  category?: NotificationCategory;
}
```

3. Filtering Logic

```typescript theme={null}
const filterNotificationsByCategory = (
  notifications: Notification[],
  category?: NotificationCategory,
) => {
  if (!category || category === "all") {
    return notifications;
  }
  return notifications.filter(
    (notification) =>
      NOTIFICATION_CONFIG[notification.type].category === category,
  );
};
```

### Visual Styling

1. Tab Design

* Use subtle background colors to differentiate tabs
* Active tab indicator with accent color
* Badge counters for unread notifications per category

2. List Organization

* Group notifications by date (Today, Yesterday, Earlier)
* Visual indicators for notification types (icons, colors)
* Clear separation between different notifications

3. Responsive Considerations

* Collapsible tabs on mobile
* Touch-friendly tab switching
* Maintain readability on smaller screens