HH/NOTIFICATION_INBOX_README.md

Notification Inbox Implementation

Overview

A complete in-app notification inbox system has been implemented for PX360. Every email sent to a user now automatically creates a corresponding in-app notification.

Features Implemented

1. Database Model: UserNotification

• Location: apps/notifications/models.py
• Fields:
  • User (ForeignKey to User)
  • Title & Message (Bilingual: EN/AR)
  • Notification Type (complaint_assigned, sla_reminder, etc.)
  • Read/Dismissed Status with timestamps
  • Related Object (GenericForeignKey)
  • Action URL for navigation
  • Link to Email Log

2. Automatic Notification Creation

• Modified: apps/notifications/services.py
• The send_email() method now automatically creates an in-app notification for every email sent
• Notifications are linked to the email log for tracking

3. API Endpoints

• GET /notifications/api/list/ - List notifications (with pagination)
• GET /notifications/api/unread-count/ - Get unread count
• GET /notifications/api/latest/ - Get latest 5 unread (for dropdown)
• POST /notifications/api/mark-read/<id>/ - Mark single as read
• POST /notifications/api/mark-all-read/ - Mark all as read
• POST /notifications/api/dismiss/<id>/ - Dismiss single
• POST /notifications/api/dismiss-all/ - Dismiss all

4. Notification Inbox Page

• URL: /notifications/inbox/
• Template: templates/notifications/inbox.html
• Features:
  • Filter tabs: All | Unread | Read
  • List view with icons, titles, timestamps
  • Mark as read / Dismiss actions
  • Bulk actions (Mark all read, Dismiss all)
  • Pagination (20 per page)
  • Empty state
  • Bilingual support (EN/AR)

5. Topbar Integration

• Modified: templates/layouts/partials/topbar.html
• Real-time unread count badge
• Dynamic dropdown showing latest 5 notifications
• "View All" link to inbox
• Auto-refresh every 30 seconds

6. Context Processor

• Modified: apps/core/context_processors.py
• Adds notification_count to all authenticated requests
• Shows unread count in topbar badge

7. Admin Interface

• Modified: apps/notifications/admin.py
• Full CRUD for UserNotification model
• Filter by type, read status, dismissed status
• Bulk actions: Mark as read, Dismiss
• Search by user email, title, message

8. Cleanup Command

• Command: python manage.py cleanup_notifications
• Options:
  • --days=30 - Configure retention period (default: 30)
  • --dry-run - Preview what would be deleted
• Deletes notifications older than 30 days
• Run via cron daily

File Structure

apps/notifications/
├── models.py                    # Added UserNotification model
├── views.py                     # Added inbox views and API endpoints
├── urls.py                      # Added notification inbox URLs
├── admin.py                     # Added UserNotificationAdmin
├── services.py                  # Modified send_email() to auto-create notifications
└── management/commands/
    └── cleanup_notifications.py # Cleanup old notifications

templates/notifications/
└── inbox.html                   # Notification inbox page

templates/layouts/
├── partials/topbar.html         # Updated with dynamic notification dropdown
└── base.html                    # Added notification polling JavaScript

apps/core/
└── context_processors.py        # Added notification_count to context

Usage

For Users:

1. View Notifications: Click bell icon in topbar
2. See All: Click "View All" in dropdown or visit /notifications/inbox/
3. Mark as Read: Click notification or "Mark as read" button
4. Dismiss: Click X button to hide notification
5. Navigate: Click notification to go to related page

For Developers:

Creating Notifications Manually:

from apps.notifications.services import create_in_app_notification

notification = create_in_app_notification(
    user=user,
    title="New Complaint Assigned",
    message="You have been assigned a new complaint",
    notification_type="complaint_assigned",
    related_object=complaint,
    action_url=f"/complaints/{complaint.id}/"
)

Auto-Created Notifications:

All emails sent via NotificationService.send_email() automatically create notifications:

from apps.notifications.services import NotificationService

NotificationService.send_email(
    email=user.email,
    subject="New Complaint",
    message="A new complaint has been assigned to you",
    notification_type="complaint_assigned",  # This creates in-app notification
    user=user  # Optional: explicit user
)

Configuration

Settings (add to settings.py):

# Notification retention period (days)
NOTIFICATION_RETENTION_DAYS = 30

Cron Job (cleanup):

Add to crontab to run daily at 3 AM:

0 3 * * * cd /path/to/project && /path/to/venv/bin/python manage.py cleanup_notifications

Testing Checklist

• Send an email and check if notification appears
• Open notification inbox page
• Mark notification as read
• Dismiss notification
• Check topbar badge updates
• Click notification to navigate
• Test bilingual content (switch language)
• Run cleanup command with --dry-run
• Admin interface works
• API endpoints return correct data

Future Enhancements (Optional)

1. Real-time Updates: Implement WebSocket for instant notifications
2. Push Notifications: Add browser push notification support
3. Email Preferences: Allow users to choose email vs in-app only
4. Notification Settings: Granular control per notification type
5. Mobile App: Push notifications for mobile app

Summary

✅ Model: UserNotification with all required fields ✅ Auto-creation: Every email creates in-app notification ✅ Inbox Page: Full-featured notification center at /notifications/inbox/ ✅ Topbar: Dynamic dropdown with real-time count ✅ API: Complete REST API for all operations ✅ Admin: Full Django admin integration ✅ Cleanup: Automated deletion of old notifications (30 days) ✅ Bilingual: EN/AR support throughout ✅ Context: notification_count available in all templates

The notification inbox is now fully functional and ready for use!