feat: implement real-time notification system with event subscription…

invofi/apps/frontend/src/app/settings/page.tsx

@@ -9,6 +9,8 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { PageHeader } from '@/components/common/PageHeader';
 import { useToast } from '@/components/ui/use-toast';
 import { createClient } from '@/utils/supabase/client';
+import { NotificationPreferencesPanel } from '@/components/notifications/NotificationPreferencesPanel';
+
 
 export default function SettingsPage() {
   const router = useRouter();
@@ -63,6 +65,15 @@ export default function SettingsPage() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-base">Notifications</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <NotificationPreferencesPanel />
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle className="text-base">Account</CardTitle>
@@ -77,3 +88,4 @@ export default function SettingsPage() {
     </div>
   );
 }
+

invofi/apps/frontend/src/components/NavbarEventIndicator.tsx

@@ -2,12 +2,20 @@
 
 import { useEventSubscription } from '@/hooks/useEventSubscription';
 import { ConnectionIndicator } from '@/components/ConnectionIndicator';
+import { NotificationBell } from '@/components/notifications/NotificationBell';
 
 /**
- * Client component that renders the connection status indicator in the navbar.
- * Extracted to keep Navbar.tsx clean and the event subscription isolated.
+ * Client component that renders the connection status indicator and notification
+ * bell in the navbar. Extracted to keep Navbar.tsx clean and the event
+ * subscription isolated.
  */
 export function NavbarEventIndicator() {
   const { status, eventCount } = useEventSubscription();
-  return <ConnectionIndicator status={status} eventCount={eventCount} />;
+  return (
+    <div className="flex items-center gap-2">
+      <NotificationBell />
+      <ConnectionIndicator status={status} eventCount={eventCount} />
+    </div>
+  );
 }
+

invofi/apps/frontend/src/components/layout/Providers.tsx

@@ -3,6 +3,7 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { useState } from 'react';
 import { WalletProvider } from '@/components/auth/WalletProvider';
+import { NotificationProvider } from '@/components/notifications/NotificationProvider';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   const [queryClient] = useState(
@@ -14,7 +15,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
   return (
     <QueryClientProvider client={queryClient}>
-      <WalletProvider>{children}</WalletProvider>
+      <WalletProvider>
+        <NotificationProvider>{children}</NotificationProvider>
+      </WalletProvider>
     </QueryClientProvider>
   );
 }
+

invofi/apps/frontend/src/components/notifications/NotificationBell.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+// ── NotificationBell (issue #255) ─────────────────────────────────────────────
+// Bell icon with unread-count badge; toggles the NotificationPanel on click.
+
+import { useState } from 'react';
+import { Bell } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useNotifications } from './NotificationProvider';
+import { NotificationPanel } from './NotificationPanel';
+
+export function NotificationBell() {
+  const { unreadCount } = useNotifications();
+  const [open, setOpen] = useState(false);
+
+  const toggle = () => setOpen((v) => !v);
+  const close = () => setOpen(false);
+
+  return (
+    <div className="relative">
+      <button
+        id="notification-bell"
+        onClick={toggle}
+        className={cn(
+          'relative flex h-9 w-9 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground',
+          open && 'bg-accent text-foreground',
+        )}
+        aria-label={
+          unreadCount > 0
+            ? `Notifications — ${unreadCount} unread`
+            : 'Notifications'
+        }
+        aria-haspopup="dialog"
+        aria-expanded={open}
+      >
+        <Bell className="h-5 w-5" />
+
+        {/* Unread badge */}
+        {unreadCount > 0 && (
+          <span
+            aria-hidden
+            className={cn(
+              'absolute -right-0.5 -top-0.5 flex h-4 min-w-[16px] items-center justify-center rounded-full bg-blue-600 px-1 text-[9px] font-bold leading-none text-white ring-1 ring-background',
+              unreadCount > 9 && 'min-w-[20px]',
+            )}
+          >
+            {unreadCount > 99 ? '99+' : unreadCount}
+          </span>
+        )}
+      </button>
+
+      <NotificationPanel open={open} onClose={close} />
+    </div>
+  );
+}

invofi/apps/frontend/src/components/notifications/NotificationItem.tsx

@@ -0,0 +1,118 @@
+'use client';
+
+// ── NotificationItem (issue #255) ─────────────────────────────────────────────
+// A single row in the notification panel.
+
+import { Bell, CheckCircle, AlertTriangle, TrendingUp, Info, X } from 'lucide-react';
+import { formatDistanceToNow } from 'date-fns';
+import { cn } from '@/lib/utils';
+import type { AppNotification, NotificationCategory } from '@/types';
+
+const CATEGORY_ICON: Record<NotificationCategory, React.ElementType> = {
+  offer: TrendingUp,
+  repayment: CheckCircle,
+  alert: AlertTriangle,
+  info: Info,
+};
+
+const CATEGORY_COLOR: Record<NotificationCategory, string> = {
+  offer: 'text-blue-500 bg-blue-50 dark:bg-blue-950/40',
+  repayment: 'text-green-500 bg-green-50 dark:bg-green-950/40',
+  alert: 'text-amber-500 bg-amber-50 dark:bg-amber-950/40',
+  info: 'text-muted-foreground bg-muted',
+};
+
+interface NotificationItemProps {
+  notification: AppNotification;
+  onMarkRead: (id: string) => void;
+  onDismiss: (id: string) => void;
+  /** Optional click handler for navigating to the relevant invoice/offer. */
+  onClick?: (notification: AppNotification) => void;
+}
+
+export function NotificationItem({
+  notification,
+  onMarkRead,
+  onDismiss,
+  onClick,
+}: NotificationItemProps) {
+  const Icon = CATEGORY_ICON[notification.category] ?? Bell;
+  const colorClass = CATEGORY_COLOR[notification.category];
+
+  const handleClick = () => {
+    if (!notification.read) onMarkRead(notification.id);
+    onClick?.(notification);
+  };
+
+  const handleDismiss = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onDismiss(notification.id);
+  };
+
+  const timeAgo = (() => {
+    try {
+      return formatDistanceToNow(new Date(notification.createdAt), { addSuffix: true });
+    } catch {
+      return '';
+    }
+  })();
+
+  return (
+    <div
+      role="listitem"
+      className={cn(
+        'group relative flex items-start gap-3 rounded-lg px-3 py-2.5 transition-colors cursor-pointer',
+        notification.read
+          ? 'hover:bg-muted/60'
+          : 'bg-blue-50/50 dark:bg-blue-950/20 hover:bg-blue-50 dark:hover:bg-blue-950/30',
+      )}
+      onClick={handleClick}
+      aria-label={`${notification.title}${notification.read ? '' : ' (unread)'}`}
+    >
+      {/* Category icon */}
+      <span
+        className={cn(
+          'mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-full',
+          colorClass,
+        )}
+        aria-hidden
+      >
+        <Icon className="h-3.5 w-3.5" />
+      </span>
+
+      {/* Content */}
+      <div className="min-w-0 flex-1">
+        <p
+          className={cn(
+            'text-sm leading-snug',
+            notification.read ? 'text-foreground/70 font-normal' : 'text-foreground font-medium',
+          )}
+        >
+          {notification.title}
+        </p>
+        <p className="mt-0.5 text-xs text-muted-foreground line-clamp-2">{notification.body}</p>
+        {timeAgo && (
+          <p className="mt-1 text-[10px] text-muted-foreground/60">{timeAgo}</p>
+        )}
+      </div>
+
+      {/* Unread dot */}
+      {!notification.read && (
+        <span
+          className="mt-1.5 h-2 w-2 shrink-0 rounded-full bg-blue-500"
+          aria-label="Unread"
+        />
+      )}
+
+      {/* Dismiss button (visible on hover) */}
+      <button
+        onClick={handleDismiss}
+        className="absolute right-2 top-2 hidden h-5 w-5 items-center justify-center rounded text-muted-foreground hover:text-foreground group-hover:flex transition-colors"
+        aria-label={`Dismiss notification: ${notification.title}`}
+        id={`dismiss-notification-${notification.id}`}
+      >
+        <X className="h-3 w-3" />
+      </button>
+    </div>
+  );
+}