NeahNew/NOTIFICATION_AND_WIDGET_ANALYSIS.md

Notification and Widget Update System - Complete File & Route Analysis

📋 Table of Contents

1. Notification System
2. Widget Update System
3. API Routes
4. Components
5. Services & Libraries
6. Hooks
7. Types

---

🔔 Notification System

API Routes

1. GET /api/notifications

• File: app/api/notifications/route.ts
• Purpose: Fetch paginated notifications for authenticated user
• Query Parameters:
  • page (default: 1)
  • limit (default: 20, max: 100)
• Response:

  {
    "notifications": Notification[],
    "page": number,
    "limit": number,
    "total": number
  }
  

• Cache: 30 seconds client-side cache
• Authentication: Required (session-based)

2. GET /api/notifications/count

• File: app/api/notifications/count/route.ts
• Purpose: Get notification count (total and unread) for authenticated user
• Response:

  {
    "total": number,
    "unread": number,
    "sources": {
      [source]: {
        "total": number,
        "unread": number
      }
    }
  }
  

• Cache: 10 seconds client-side cache
• Authentication: Required

3. POST /api/notifications/[id]/read

• File: app/api/notifications/[id]/read/route.ts
• Purpose: Mark a specific notification as read
• Parameters:
  • id (path parameter): Notification ID (format: source-sourceId)
• Response:

  {
    "success": boolean
  }
  

• Authentication: Required

4. POST /api/notifications/read-all

• File: app/api/notifications/read-all/route.ts
• Purpose: Mark all notifications as read for authenticated user
• Response:

  {
    "success": boolean
  }
  

• Authentication: Required

5. GET /api/debug/notifications

• File: app/api/debug/notifications/route.ts
• Purpose: Debug endpoint to test notification system
• Response: Detailed debug information including:
  • Environment variables status
  • User information
  • Notification service test results
  • Performance metrics
• Authentication: Required

Services

1. NotificationService (Singleton)

• File: lib/services/notifications/notification-service.ts
• Purpose: Core notification aggregation service
• Features:
  • Multi-source notification aggregation (adapter pattern)
  • Redis caching (30s for counts, 5min for lists)
  • Background refresh scheduling
  • Cache invalidation on read operations
  • Lock mechanism to prevent concurrent refreshes
• Methods:
  • getInstance(): Get singleton instance
  • getNotifications(userId, page, limit): Fetch notifications
  • getNotificationCount(userId): Get notification counts
  • markAsRead(userId, notificationId): Mark notification as read
  • markAllAsRead(userId): Mark all as read
  • invalidateCache(userId): Invalidate user caches
  • scheduleBackgroundRefresh(userId): Schedule background refresh

2. NotificationAdapter Interface

• File: lib/services/notifications/notification-adapter.interface.ts
• Purpose: Interface for notification source adapters
• Methods:
  • getNotifications(userId, page?, limit?): Fetch notifications
  • getNotificationCount(userId): Get counts
  • markAsRead(userId, notificationId): Mark as read
  • markAllAsRead(userId): Mark all as read
  • isConfigured(): Check if adapter is configured

3. LeantimeAdapter (Implementation)

• File: lib/services/notifications/leantime-adapter.ts
• Purpose: Leantime notification source adapter
• Features:
  • Fetches notifications from Leantime API via JSON-RPC
  • Maps Leantime user IDs by email
  • Transforms Leantime notifications to unified format
  • Supports marking notifications as read
• Configuration:
  • LEANTIME_API_URL environment variable
  • LEANTIME_TOKEN environment variable

Components

1. NotificationBadge

• File: components/notification-badge.tsx
• Purpose: Notification bell icon with badge and dropdown
• Features:
  • Displays unread count badge
  • Dropdown menu with recent notifications
  • Manual refresh button
  • Mark as read functionality
  • Mark all as read functionality
  • Source badges (e.g., "Agilité" for Leantime)
  • Links to source systems
  • Error handling and retry
• Used in: components/main-nav.tsx

2. MainNav (Notification Integration)

• File: components/main-nav.tsx
• Purpose: Main navigation bar with notification badge
• Notification Features:
  • Includes <NotificationBadge /> component
  • Browser notification permission handling
  • User status-based notification management

Hooks

1. useNotifications

• File: hooks/use-notifications.ts
• Purpose: React hook for notification management
• Features:
  • Automatic polling (60 seconds interval)
  • Rate limiting (5 seconds minimum between fetches)
  • Debounced count fetching (300ms)
  • Manual refresh support
  • Mount/unmount lifecycle management
  • Error handling
• Returns:

  {
    notifications: Notification[],
    notificationCount: NotificationCount,
    loading: boolean,
    error: string | null,
    fetchNotifications: (page?, limit?) => Promise<void>,
    fetchNotificationCount: () => Promise<void>,
    markAsRead: (notificationId: string) => Promise<boolean>,
    markAllAsRead: () => Promise<boolean>
  }
  

Types

1. Notification Types

• File: lib/types/notification.ts
• Interfaces:
  • Notification: Main notification interface
    • id: string (format: source-sourceId)
    • source: 'leantime' | 'nextcloud' | 'gitea' | 'dolibarr' | 'moodle'
    • sourceId: string
    • type: string
    • title: string
    • message: string
    • link?: string
    • isRead: boolean
    • timestamp: Date
    • priority: 'low' | 'normal' | 'high'
    • user: { id: string, name?: string }
    • metadata?: Record<string, any>
  • NotificationCount: Count interface
    • total: number
    • unread: number
    • sources: Record<string, { total: number, unread: number }>

---

🎨 Widget Update System

Dashboard Widgets

The main dashboard (app/page.tsx) contains the following widgets:

1. QuoteCard - Daily quote widget
2. Calendar - Upcoming events widget
3. News - News articles widget
4. Duties - Tasks/Devoirs widget (Leantime)
5. Email - Email inbox widget
6. Parole - Chat messages widget (Rocket.Chat)

Widget Components & Update Mechanisms

1. Calendar Widget

• Files:
  • components/calendar.tsx (Main dashboard widget)
  • components/calendar-widget.tsx (Alternative implementation)
  • components/calendar/calendar-widget.tsx (Calendar-specific widget)
• Update Mechanism:
  • Manual Refresh: Refresh button in header
  • Auto Refresh: Every 5 minutes (300000ms interval)
  • API Endpoint: /api/calendars?refresh=true
  • Features:
    • Fetches calendars with events
    • Filters upcoming events (today and future)
    • Sorts by date (oldest first)
    • Shows up to 7 events
    • Displays calendar color coding
• State Management:
  • useState for events, loading, error
  • useEffect for initial fetch and interval setup

2. News Widget

• File: components/news.tsx
• Update Mechanism:
  • Manual Refresh: Refresh button in header
  • Initial Load: On component mount when authenticated
  • API Endpoint: /api/news?limit=100 or /api/news?refresh=true&limit=100
  • Features:
    • Fetches up to 100 news articles
    • Displays article count
    • Click to open in new tab
    • Scrollable list (max-height: 400px)
• State Management:
  • useState for news, loading, error, refreshing
  • useEffect for initial fetch on authentication

3. Duties Widget (Tasks)

• File: components/flow.tsx
• Update Mechanism:
  • Manual Refresh: Refresh button in header
  • Initial Load: On component mount
  • API Endpoint: /api/leantime/tasks?refresh=true
  • Features:
    • Fetches tasks from Leantime
    • Filters out completed tasks (status 5)
    • Sorts by due date (oldest first)
    • Shows up to 7 tasks
    • Displays task status badges
    • Links to Leantime ticket view
• State Management:
  • useState for tasks, loading, error, refreshing
  • useEffect for initial fetch

4. Email Widget

• File: components/email.tsx
• Update Mechanism:
  • Manual Refresh: Refresh button in header
  • Initial Load: On component mount
  • API Endpoint: /api/courrier?folder=INBOX&page=1&perPage=5 (+ &refresh=true for refresh)
  • Features:
    • Fetches 5 most recent emails from INBOX
    • Sorts by date (most recent first)
    • Shows read/unread status
    • Displays sender, subject, date
    • Link to full email view (/courrier)
• State Management:
  • useState for emails, loading, error, mailUrl
  • useEffect for initial fetch

5. Parole Widget (Chat Messages)

• File: components/parole.tsx
• Update Mechanism:
  • Manual Refresh: Refresh button in header
  • Auto Polling: Every 30 seconds (30000ms interval)
  • Initial Load: On authentication
  • API Endpoint: /api/rocket-chat/messages (+ ?refresh=true for refresh)
  • Features:
    • Fetches recent chat messages from Rocket.Chat
    • Displays sender avatar, name, message
    • Shows room/channel information
    • Click to navigate to full chat (/parole)
    • Authentication check with sign-in prompt
• State Management:
  • useState for messages, loading, error, refreshing
  • useEffect for initial fetch and polling setup
  • Session status checking

6. QuoteCard Widget

• File: components/quote-card.tsx
• Update Mechanism: (To be verified - likely static or daily update)

Widget Update Patterns

Common Update Mechanisms:

1. Manual Refresh:

   • All widgets have a refresh button in their header
   • Triggers API call with refresh=true parameter
   • Shows loading/spinning state during refresh

2. Auto Refresh/Polling:

   • Calendar: 5 minutes interval
   • Parole: 30 seconds interval
   • Others: On component mount only

3. Session-Based Loading:

   • Widgets check authentication status
   • Only fetch data when status === 'authenticated'
   • Show loading state during authentication check

4. Error Handling:

   • All widgets display error messages
   • Retry buttons available
   • Graceful degradation (empty states)

5. State Management:

   • All widgets use React useState hooks
   • Loading states managed locally
   • Error states managed locally

Related API Routes for Widgets

Calendar

• GET /api/calendars: Fetch calendars with events
• GET /api/calendars/[id]/events: Fetch events for specific calendar
• GET /api/calendars/[id]: Get calendar details

News

• GET /api/news: Fetch news articles
  • Query params: limit, refresh

Tasks (Leantime)

• GET /api/leantime/tasks: Fetch tasks
  • Query params: refresh

Email (Courrier)

• GET /api/courrier: Fetch emails
  • Query params: folder, page, perPage, refresh
• POST /api/courrier/refresh: Force refresh email cache

Chat (Rocket.Chat)

• GET /api/rocket-chat/messages: Fetch messages
  • Query params: refresh

---

📁 Complete File Structure

Notification Files

app/api/notifications/
├── route.ts                    # GET /api/notifications
├── count/
│   └── route.ts               # GET /api/notifications/count
├── read-all/
│   └── route.ts               # POST /api/notifications/read-all
└── [id]/
    └── read/
        └── route.ts            # POST /api/notifications/[id]/read

app/api/debug/
└── notifications/
    └── route.ts                # GET /api/debug/notifications

lib/services/notifications/
├── notification-service.ts     # Core notification service
├── notification-adapter.interface.ts  # Adapter interface
└── leantime-adapter.ts         # Leantime adapter implementation

lib/types/
└── notification.ts             # Notification type definitions

hooks/
└── use-notifications.ts        # React hook for notifications

components/
├── notification-badge.tsx      # Notification UI component
└── main-nav.tsx                # Navigation with notification badge

Widget Files

app/
└── page.tsx                    # Main dashboard with widgets

components/
├── calendar.tsx                # Calendar widget
├── calendar-widget.tsx         # Alternative calendar widget
├── calendar/
│   └── calendar-widget.tsx     # Calendar-specific widget
├── news.tsx                     # News widget
├── flow.tsx                     # Duties/Tasks widget
├── email.tsx                    # Email widget
├── parole.tsx                   # Chat messages widget
└── quote-card.tsx              # Quote widget

app/api/
├── calendars/
│   ├── route.ts                # GET /api/calendars
│   └── [id]/
│       └── events/
│           └── route.ts         # GET /api/calendars/[id]/events
├── news/
│   └── route.ts                # GET /api/news
├── leantime/
│   └── tasks/
│       └── route.ts            # GET /api/leantime/tasks
├── courrier/
│   ├── route.ts                # GET /api/courrier
│   └── refresh/
│       └── route.ts            # POST /api/courrier/refresh
└── rocket-chat/
    └── messages/
        └── route.ts            # GET /api/rocket-chat/messages

---

🔄 Update Flow Diagrams

Notification Update Flow

User Action / Polling
    ↓
useNotifications Hook
    ↓
API Route (/api/notifications or /api/notifications/count)
    ↓
NotificationService.getInstance()
    ↓
Check Redis Cache
    ├─ Cache Hit → Return cached data
    └─ Cache Miss → Fetch from Adapters
         ↓
    LeantimeAdapter (and other adapters)
         ↓
    Transform & Aggregate
         ↓
    Store in Redis Cache
         ↓
    Return to API
         ↓
    Return to Hook
         ↓
    Update Component State

Widget Update Flow

Component Mount / User Click Refresh
    ↓
useEffect / onClick Handler
    ↓
fetch() API Call
    ├─ With refresh=true (manual)
    └─ Without refresh (initial)
    ↓
API Route Handler
    ├─ Check Cache (if applicable)
    ├─ Fetch from External Service
    └─ Return Data
    ↓
Update Component State
    ├─ setLoading(false)
    ├─ setData(response)
    └─ setError(null)
    ↓
Re-render Component

---

🎯 Key Features Summary

Notification System

• ✅ Multi-source aggregation (adapter pattern)
• ✅ Redis caching with TTL
• ✅ Background refresh scheduling
• ✅ Polling mechanism (60s interval)
• ✅ Rate limiting (5s minimum)
• ✅ Mark as read / Mark all as read
• ✅ Cache invalidation on updates
• ✅ Error handling and retry
• ✅ Source badges and links

Widget System

• ✅ Manual refresh buttons
• ✅ Auto-refresh/polling (widget-specific intervals)
• ✅ Session-based loading
• ✅ Error handling
• ✅ Loading states
• ✅ Empty states
• ✅ Responsive design

---

📝 Notes

1. Notification Sources: Currently only Leantime adapter is implemented. Other adapters (Nextcloud, Gitea, Dolibarr, Moodle) are commented out in the service.

2. Cache Strategy:

   • Notification counts: 30 seconds TTL
   • Notification lists: 5 minutes TTL
   • Widget data: Varies by widget (some use API-level caching)

3. Polling Intervals:

   • Notifications: 60 seconds
   • Calendar widget: 5 minutes
   • Parole widget: 30 seconds
   • Other widgets: On mount only

4. Authentication: All notification and widget APIs require authentication via NextAuth session.

5. Error Handling: All components implement error states with retry mechanisms.

---

🔍 Debugging

• Use /api/debug/notifications to test notification system
• Check browser console for detailed logs (all components log extensively)
• Check Redis cache keys: notifications:count:{userId}, notifications:list:{userId}:{page}:{limit}

---

Last Updated: Generated from codebase analysis