Notifications & Alerts

Relevant source files

The following files were used as context for generating this wiki page:

• supabase/migrations/20251229000000_approvals_system.sql
• components/layout/notifications-popover.tsx
• app/(app)/help/page.tsx
• testsprite_tests/standard_prd.json
• CHANGELOG.md
• scripts/help-center-data.ts

The Notifications & Alerts system in DRX CRM provides real-time communication of critical business events, system updates, and administrative tasks. Its primary purpose is to ensure operational awareness and facilitate the Inventory Management approval workflow by notifying relevant personnel of pending actions and system status changes.

The system is built on a PostgreSQL backend with Supabase, utilizing database triggers for automated alerting and a React-based frontend popover for user interaction. It supports multi-tenancy through strict row-level security (RLS), ensuring users only receive notifications relevant to their specific business ID and role.

Sources: supabase/migrations/20251229000000_approvals_system.sql:7-18, README.md:12-25, testsprite_tests/standard_prd.json:20-25

Data Architecture

Database Schema

The foundation of the system is the notifications table, which stores the content, type, and status of every alert. It includes a metadata JSONB column for storing context-specific identifiers, such as intake IDs for approval workflows.

Field	Type	Description
id	UUID	Primary key, default random UUID.
user_id	UUID	References auth.users(id). Target recipient.
business_id	UUID	References business_profile(id). Tenant isolation.
type	VARCHAR	Category: 'approval', 'system', or 'alert'.
title	TEXT	Short summary of the notification.
message	TEXT	Detailed content of the alert.
link	TEXT	Optional URL for the user to take action.
is_read	BOOLEAN	Read status tracking, defaults to FALSE.
metadata	JSONB	Additional context (e.g., product IDs).

Sources: supabase/migrations/20251229000000_approvals_system.sql:10-21

Notification Types

The system categorizes notifications into three distinct types to drive different UI behaviors and urgency levels:

1. Approval: High-priority alerts requiring manager intervention (e.g., inventory intake requests).
2. Alert: Informational status updates for users (e.g., approval/rejection of their requests).
3. System: Broad platform-wide updates or low-stock warnings.

Sources: supabase/migrations/20251229000000_approvals_system.sql:14, components/layout/notifications-popover.tsx:18, scripts/help-center-data.ts:397-402

Automated Notification Logic

Notifications are primarily generated server-side via PL/pgSQL functions and database triggers. This ensures that alerts are fired immediately upon data mutation, regardless of the client used.

Trigger Flow: Inventory Approvals

When a user submits an inventory intake, the notify_managers_on_intake function identifies all users with managerial roles for that specific business and generates individual notification records.

The system identifies managers based on explicit roles ('manager', 'admin', 'owner') or specific permission flags like can_approve_intakes.

Sources: supabase/migrations/20251229000000_approvals_system.sql:53-75, testsprite_tests/standard_prd.json:106-115

User Decision Alerts

When a manager approves or rejects a request, a secondary trigger notify_user_on_intake_decision fires to inform the original requester of the outcome.

Frontend Integration

Notifications Popover

The user interface for notifications is implemented in the NotificationsPopover component. It resides in the global layout and provides a bell icon with an unread badge.

Key Features:

• Real-time Polling: The client fetches new notifications from /api/notifications every 30 seconds.
• State Management: Tracks unreadCount and notifications list locally to provide immediate UI feedback.
• Interaction: Clicking a notification marks it as read via a PUT request to the API. If the notification contains a link, the user is navigated to the relevant action page (e.g., /admin/approvals).

Sources: components/layout/notifications-popover.tsx:31-68, test-results/neon-velocity-Neon-Velocit-d29de--have-Neon-Velocity-styling-chromium/error-context.md:144

Implementation Example

// components/layout/notifications-popover.tsx
const markAsRead = async (id?: string) => {
  const res = await fetch("/api/notifications", {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(id ? { id } : { mark_all_read: true }),
  });
  // ... update local state
};

Sources: components/layout/notifications-popover.tsx:50-54

Security and Compliance

Tenant Isolation (RLS)

Security is enforced at the database level using Supabase Row Level Security (RLS). This ensures that users cannot view or modify notifications belonging to other businesses or users.

• Select Policy: auth.uid() = user_id ensures private visibility.
• Update Policy: Users can only update is_read status on their own records.
• Insert Policy: The "System" is granted permission to insert notifications to allow triggers and edge functions to generate alerts.

Sources: supabase/migrations/20251229000000_approvals_system.sql:26-38, testsprite_tests/standard_prd.json:20-25

Audit Trails

All sensitive actions that trigger notifications, such as inventory adjustments or intake decisions, are also recorded in the system_audit_log. These logs are immutable and provide a permanent record for compliance and troubleshooting.

Sources: testsprite_tests/standard_prd.json:96-103, README.md:25

Summary

The Notifications & Alerts system is a central nervous system for DRX CRM, bridging the gap between automated database events and user action. By combining PostgreSQL triggers for reliability and a React-based polling mechanism for the UI, it provides a robust framework for managing approvals and system-wide communications while maintaining strict multi-tenant security.