docs: add notification system quick start guide

2025-11-17 00:35:45 +00:00
parent 53a3ccc4a0
commit b48d52fcf3
1 changed files with 178 additions and 0 deletions
--- a/server/NOTIFICATION_QUICK_START.md
+++ b/server/NOTIFICATION_QUICK_START.md
@@ -0,0 +1,178 @@
+# Notification System - Quick Start Guide
+
+## 🚀 Get Started in 3 Steps
+
+### Step 1: Authorize Your Email in Mailgun
+
+1. Go to https://app.mailgun.com/
+2. Navigate to: **Sending** → **Domains** → `sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org`
+3. Scroll to **"Authorized Recipients"**
+4. Add your email: `psbailey31@gmail.com`
+5. Click **"Invite"**
+6. Check your email and click the confirmation link
+
+### Step 2: Test Email Delivery
+
+```bash
+cd server
+npx tsx src/scripts/testEmail.ts
+```
+
+Expected output:
+```
+✅ Test email sent successfully to psbailey31@gmail.com
+✅ Notification email sent successfully to psbailey31@gmail.com
+```
+
+Check your inbox (and spam folder)!
+
+### Step 3: Test Full Notification System
+
+```bash
+cd server
+npx tsx src/scripts/testNotifications.ts
+```
+
+This tests:
+- ✅ Email service connection
+- ✅ Notification creation
+- ✅ Area-of-interest matching
+- ✅ Mark as read functionality
+- ✅ Event reminders
+
+## 📧 Configuration
+
+Already configured in `.env`:
+
+```env
+MAILGUN_API_KEY="dd27be7a81dd7b0980ada31fec9a9bd9-e80d8b76-fd80c63b"
+MAILGUN_DOMAIN="sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org"
+FROM_EMAIL="Beach Litter Platform <noreply@sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org>"
+TEST_EMAIL="psbailey31@gmail.com"
+```
+
+## 🔔 How It Works
+
+### For Users
+
+1. **Set Areas of Interest**:
+   - Go to Profile → Notification Settings
+   - Add locations with radius (1-50km)
+   - Enable email/in-app notifications
+
+2. **Receive Notifications**:
+   - Bell icon in header shows unread count
+   - Click to see notification list
+   - Click notification to view details
+   - Automatically marked as read
+
+3. **Email Notifications**:
+   - Receive formatted HTML emails
+   - Click links to view details
+   - Manage preferences in profile
+
+### For Developers
+
+1. **Automatic Triggers**:
+   ```typescript
+   // Report created → notifications sent
+   await reportService.createReport(data);
+   // Automatically triggers notificationService.notifyNewReport()
+   
+   // Event created → notifications sent
+   await eventService.createEvent(data);
+   // Automatically triggers notificationService.notifyNewEvent()
+   ```
+
+2. **Manual Notifications**:
+   ```typescript
+   import { notificationService } from './services/notificationService';
+   
+   await notificationService.createNotification({
+     userId: 'user-id',
+     type: 'new_report',
+     title: 'New Report',
+     message: 'A new report was created',
+     relatedId: 'report-id',
+     relatedType: 'report',
+     latitude: 53.3498,
+     longitude: -6.2603,
+   });
+   ```
+
+3. **Scheduled Jobs**:
+   - Event reminders: Every 10 minutes
+   - Cleanup old notifications: Daily at 2 AM
+
+## 🎯 API Endpoints
+
+All require authentication:
+
+```bash
+# Get notifications
+GET /api/notifications?unreadOnly=true
+
+# Get unread count
+GET /api/notifications/unread-count
+
+# Mark as read
+PATCH /api/notifications/:id/read
+
+# Mark all as read
+PATCH /api/notifications/read-all
+```
+
+## 🐛 Troubleshooting
+
+### "Forbidden" Error
+
+**Problem**: Email not authorized in Mailgun sandbox
+
+**Solution**: 
+1. Add email to authorized recipients
+2. Confirm authorization email
+3. Wait 2-3 minutes
+4. Try again
+
+### Notifications Not Appearing
+
+**Problem**: User has no areas of interest
+
+**Solution**:
+1. Go to Profile → Notification Settings
+2. Add at least one area of interest
+3. Create a report/event in that area
+4. Check notification bell
+
+### Emails Going to Spam
+
+**Problem**: Sandbox domain has low reputation
+
+**Solution**:
+1. Check spam folder
+2. Mark as "Not Spam"
+3. For production, use custom domain
+
+## 📚 Full Documentation
+
+- **Implementation Guide**: `NOTIFICATION_SYSTEM_IMPLEMENTATION.md`
+- **Mailgun Setup**: `MAILGUN_SETUP.md`
+- **Task Summary**: `TASK_33_NOTIFICATION_SYSTEM_COMPLETE.md`
+
+## ✅ Checklist
+
+- [ ] Authorized email in Mailgun dashboard
+- [ ] Confirmed authorization email
+- [ ] Ran test email script successfully
+- [ ] Ran full notification test successfully
+- [ ] Checked inbox for test emails
+- [ ] Tested notification bell in UI
+- [ ] Set up areas of interest for test user
+- [ ] Created test report/event
+- [ ] Verified notification received
+
+## 🎉 You're Done!
+
+The notification system is ready to use. Users will now receive notifications about reports and events in their areas of interest!
+
+For production deployment, see `MAILGUN_SETUP.md` for custom domain setup.