Notifications

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/EdgarJr30/proyecto-de-grado-cms/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Notification Categories

​

Notification Center

​

Feed View

• Chronological list of notifications
• Visual distinction between read/unread
• Search by title, message, or category
• Quick mark as read/unread
• Click to navigate to related entity
• Real-time updates

​

Settings Panel

1. Push Notifications
   • Enable/disable push on current device
   • Platform-specific instructions
   • Permission status indicator
   • Test notification sender
2. Category Preferences
   • Toggle each category on/off
   • Affects both in-app and push
   • Saved per user
3. Admin Tools (if permitted)
   • Send test notifications to any user
   • Search users by name/email
   • View push subscription status
   • Test both in-app and push delivery

​

Notification States

​

Delivered At

​

Seen At

​

Read At

​

Web Push Notifications

​

Enabling Push

​

Platform-Specific Instructions

• Install app to home screen first
• Open installed PWA
• Allow notifications when prompted
• Check Settings > [App Name] > Notifications

• Browser or PWA supported
• Allow notifications when prompted
• Check Settings > Apps > [Browser/App] > Notifications

• Browser permission prompt
• Check Settings > System > Notifications
• Verify browser notifications enabled

• Browser permission prompt
• Check System Preferences > Notifications
• Verify browser notifications enabled

​

Push Architecture

1. Subscription - Device registers with push service
   • Table: web_push_subscriptions
   • Stores endpoint, keys, user_agent
   • One per device per user
2. Outbox - Queue for pending push messages
   • Table: web_push_outbox
   • Created by triggers on notification events
   • Processed by Edge Function
3. Edge Function - Sends push messages
   • Function: send-push-from-outbox
   • Triggered by cron (every minute)
   • Uses Web Push protocol
   • Marks delivered or failed
4. Client - Receives and displays push
   • Service worker intercepts
   • Shows browser notification
   • Handles click to open app

Event → Trigger → Outbox Entry → Edge Function → Push Service → Device

​

Event System

​

Notification Events

interface NotificationEvent {
  id: string; // UUID
  event_type: string; // e.g., 'ticket.assigned'
  actor_user_id: string | null; // Who triggered the event
  entity_type: string; // e.g., 'ticket'
  entity_id: string; // e.g., ticket ID
  payload: Record<string, unknown>; // Custom data
  created_at: string;
}

​

Common Event Types

• ticket.created
• ticket.assigned
• ticket.unassigned
• ticket.status_changed
• ticket.accepted
• ticket.finalized
• ticket.comment_added
• ticket.priority_changed
• ticket.urgent_changed
• ticket.deadline_set
• ticket.deadline_changed
• ticket.due_soon
• ticket.overdue

​

Delivery Records

interface NotificationDelivery {
  id: string; // UUID
  event_id: string; // References notification_events
  recipient_user_id: string;
  channel_mask: number; // Bitmask: 1=in-app, 2=push, 4=email
  read_at: string | null;
  seen_at: string | null;
  delivered_at: string | null;
  created_at: string;
}

​

Service Integration

​

Listing Notifications

import { listNotifications } from '@/services/notificationCenterService';

const { items, total } = await listNotifications({
  scope: 'unread', // 'all' | 'unread' | 'tickets' | 'admin'
  offset: 0,
  limit: 20,
});

items.forEach((item) => {
  console.log(item.title, item.message, item.category);
});

​

Marking as Read

import { markNotificationRead, markAllNotificationsRead } from '@/services/notificationCenterService';

// Mark single notification
await markNotificationRead(deliveryId);

// Mark all notifications
await markAllNotificationsRead();

​

Unread Count

import { getUnreadNotificationsCount } from '@/services/notificationCenterService';

const count = await getUnreadNotificationsCount();
console.log(`${count} unread notifications`);

​

Preferences

import { 
  getMyNotificationPreferences, 
  saveMyNotificationPreferences 
} from '@/services/notificationCenterService';

// Load preferences
const prefs = await getMyNotificationPreferences();

// Update preferences
const updated = await saveMyNotificationPreferences({
  push_enabled: true,
  categories: {
    assignments: true,
    comments: true,
    status_changes: true,
    deadlines: true,
    admin_system: false,
  },
});

​

Real-time Subscription

import { subscribeToMyNotificationDeliveries } from '@/services/notificationCenterService';

const unsubscribe = subscribeToMyNotificationDeliveries(
  userId,
  () => {
    // Callback when new notification arrives
    refreshNotifications();
  }
);

// Clean up on unmount
return () => unsubscribe();

​

Data Model

​

NotificationItem

type NotificationItem = {
  deliveryId: string;
  eventId: string;
  eventType: string; // e.g., 'ticket.assigned'
  actorUserId: string | null;
  entityType: string; // e.g., 'ticket'
  entityId: string;
  category: NotificationCategory;
  channelMask: number;
  title: string;
  message: string;
  url: string; // Navigation target
  createdAt: string;
  readAt: string | null;
  seenAt: string | null;
  deliveredAt: string | null;
  payload: Record<string, unknown>;
};

​

NotificationPreferences

type NotificationPreferences = {
  push_enabled: boolean;
  categories: Record<NotificationCategory, boolean>;
  quiet_hours?: {
    from?: string; // e.g., '22:00'
    to?: string;   // e.g., '08:00'
  };
};

​

NotificationCategory

type NotificationCategory =
  | 'assignments'
  | 'comments'
  | 'status_changes'
  | 'deadlines'
  | 'admin_system';

​

UI Components

​

NotificationCenterPage

• Feed with filtering and search
• Settings panel with preferences
• Push onboarding guide
• Admin test tools
• Responsive mobile/desktop layout

​

SwipeableNotificationCard

• Tap to open
• Swipe right for quick actions
• Long press for context menu

​

Badge Components

import { useUnreadNotificationsCount } from '@/hooks/useUnreadNotificationsCount';

const count = useUnreadNotificationsCount();

{count > 0 && (
  <span className="badge">{count}</span>
)}

​

Permissions

​

View Notifications

• View their own notifications
• Mark notifications as read/unread
• Configure preferences
• Enable/disable push

​

Send Test Notifications

• users:full_access
• rbac:manage_permissions

• Search all users
• Send test notifications to any user
• View push subscription status

​

Performance

​

Pagination

• Default page size: 20 notifications
• Client-side pagination controls
• Server-side filtering and counting
• Efficient range(offset, limit) queries

​

Caching

• Unread count cached in memory
• Refreshed on notification events
• Invalidated on mark as read/unread

​

Real-time Efficiency

• Uses Supabase Realtime channels
• Filters by recipient_user_id
• Only subscribes to own notifications
• Automatic reconnection on disconnect

​

Troubleshooting

​

Push not working

​

Notifications not appearing

• Check category preferences (might be disabled)
• Verify RLS policies allow access
• Confirm event was created
• Check delivery records in database
• Review browser console for errors

​

Unread count wrong

• Refresh the page
• Mark all as read and verify
• Check read_at in database
• Clear browser cache

​

Best Practices

​

For Users

1. Enable Push - Stay informed of urgent updates
2. Review Daily - Check notification center regularly
3. Mark as Read - Keep unread count manageable
4. Configure Categories - Disable categories you don’t need
5. Test Regularly - Verify push works after device changes

​

For Developers

1. Use Correct Event Types - Follow naming convention
2. Populate Payload - Include useful context data
3. Set Meaningful Titles - Make notifications actionable
4. Test on All Platforms - iOS, Android, desktop
5. Handle Errors Gracefully - Push may fail, show in-app

​

For Admins

1. Monitor Outbox - Check for stuck messages
2. Review Edge Function Logs - Identify delivery issues
3. Validate VAPID Keys - Ensure configured correctly
4. Test User Notifications - Use admin test tool
5. Clean Old Notifications - Archive old deliveries

​

Related Documentation

• Work Orders - Notifications for status changes
• Work Requests - Notifications for new requests
• My Tickets - Notifications for your assignments
• Kanban Board - Real-time board updates