# AeThex Complete Notification System

## Overview

A comprehensive notification system covering 15+ user interactions across social, collaboration, opportunities, and security features.

## All Notification Flows

### 1. Achievements (✅ Success)

**When:** User earns an achievement  
**Who Notified:** Achievement earner  
**Format:** `🏆 Achievement Unlocked: {name}` - "{xp} XP awarded"  
**Service:** `aethexAchievementService.awardAchievement()`

### 2. Team Creation (✅ Success)

**When:** Team is created  
**Who Notified:** Team creator  
**Format:** `🎯 Team Created: {name}` - "Your team is ready to go!"  
**Service:** `aethexCollabService.createTeam()`

### 3. Added to Team (ℹ️ Info)

**When:** User is added to a team  
**Who Notified:** New team member  
**Format:** `👥 Added to Team: {name}` - "You've been added as a {role}"  
**Service:** `aethexCollabService.addTeamMember()`

### 4. Project Creation (✅ Success)

**When:** Project is created  
**Who Notified:** Project creator  
**Format:** `🚀 Project Created: {name}` - "Your project is ready to go!"  
**Service:** `aethexProjectService.createProject()`

### 5. Added to Project (ℹ️ Info)

**When:** User is added to a project  
**Who Notified:** New project member  
**Format:** `📌 Added to Project: {name}` - "You've been added as a {role}"  
**Service:** `aethexCollabService.addProjectMember()`

### 6. Project Completed (✅ Success)

**When:** Project status changes to completed  
**Who Notified:** Project owner  
**Format:** `✅ Project Completed: {name}` - "Congratulations!"  
**Service:** `aethexProjectService.updateProject(status: "completed")`

### 7. Project Started (ℹ️ Info)

**When:** Project status changes to in_progress  
**Who Notified:** Project owner  
**Format:** `⏱️ Project Started: {name}` - "You've started working on this"  
**Service:** `aethexProjectService.updateProject(status: "in_progress")`

### 8. Level Up (✅ Success)

**When:** User gains enough XP to level up  
**Who Notified:** User  
**Format:** `⬆️ Level Up!` - "You've reached level {n}!"  
**Service:** `aethexAchievementService.updateUserXPAndLevel()`

### 9. Onboarding Complete (✅ Success)

**When:** User finishes onboarding  
**Who Notified:** User  
**Format:** `🎉 Welcome to AeThex!` - "Profile setup complete!"  
**Service:** `Onboarding.tsx -> finishOnboarding()`

### 10. Account Linked (✅ Success)

**When:** User links OAuth provider (Discord, GitHub, etc.)  
**Who Notified:** User  
**Format:** `🔗 Account Linked: {provider}` - "Successfully linked"  
**Service:** OAuth callback endpoints

### 11. Email Verified (✅ Success)

**When:** User verifies email  
**Who Notified:** User  
**Format:** `✉️ Email Verified` - "Your email has been verified"  
**Service:** Auth flow (future implementation)

### 12. Post Liked (ℹ️ Info)

**When:** Someone likes a community post  
**Who Notified:** Post author  
**Format:** `❤️ Your post was liked` - "{liker} liked your post"  
**Endpoint:** `POST /api/community/posts/:id/like`  
**Service:** `notificationTriggers.postLiked()`

### 13. Post Commented (ℹ️ Info)

**When:** Someone comments on a community post  
**Who Notified:** Post author  
**Format:** `💬 New comment on your post` - "{commenter} commented: {preview}"  
**Endpoint:** `POST /api/community/posts/:id/comments`  
**Service:** `notificationTriggers.postCommented()`

### 14. Endorsement Received (✅ Success)

**When:** User endorses another user's skill  
**Who Notified:** Endorsed user  
**Format:** `🎖️ New endorsement` - "{endorser} endorsed you for {skill}"  
**Endpoint:** `POST /api/social/endorse`

### 15. New Follower (ℹ️ Info)

**When:** Someone follows a user  
**Who Notified:** Followed user  
**Format:** `👥 New follower` - "{follower} started following you"  
**Endpoint:** `POST /api/social/follow`

### 16. Task Assigned (ℹ️ Info)

**When:** Task is assigned to user  
**Who Notified:** Assignee  
**Format:** `📋 Task assigned to you` - "{assigner} assigned: {title}"  
**Endpoints:**

- `POST /api/tasks` (on create with assignee)
- `PUT /api/tasks/:id/assign`  
  **Service:** `notificationTriggers.taskAssigned()`

### 17. Application Received (ℹ️ Info)

**When:** Creator applies for an opportunity  
**Who Notified:** Opportunity poster  
**Format:** `📋 New Application: {title}` - "{creator} applied"  
**Endpoint:** `POST /api/applications`  
**Service:** `notificationTriggers.applicationReceived()`

### 18. Application Status Changed (✅/❌ Success/Error)

**When:** Application is accepted/rejected  
**Who Notified:** Applicant  
**Format:** `✅/❌ Application {status}` - "{message}"  
**Endpoint:** `PUT /api/applications/:id`  
**Service:** `notificationTriggers.applicationStatusChanged()`

### 19. New Device Login (⚠️ Warning)

**When:** User logs in from new device  
**Who Notified:** User  
**Format:** `🔐 New device login detected` - "New login from {device}. If this wasn't you, secure your account."  
**Endpoint:** `POST /api/auth/login-device`  
**Service:** `notificationTriggers.newDeviceLogin()`

### 20. Moderation Report (⚠️ Warning)

**When:** User submits moderation report  
**Who Notified:** All staff/moderators  
**Format:** `🚨 New moderation report` - "A {type} report has been submitted"  
**Endpoint:** `POST /api/moderation/reports`  
**Service:** `notificationTriggers.moderationReportSubmitted()`

## Notification Types

| Type      | Color     | Icon | Use Cases                                   |
| --------- | --------- | ---- | ------------------------------------------- |
| `success` | 🟢 Green  | ✅   | Achievements, completion, account actions   |
| `info`    | 🔵 Blue   | ℹ️   | Team/project updates, social interactions   |
| `warning` | 🟡 Yellow | ⚠️   | Security alerts, moderation reports         |
| `error`   | 🔴 Red    | ❌   | Rejections, failed actions, security issues |

## Integration Points

### Client Services

- `code/client/lib/aethex-database-adapter.ts` - Project, achievement, profile notifications
- `code/client/lib/aethex-collab-service.ts` - Team/project member notifications
- `code/client/lib/notification-triggers.ts` - Centralized trigger utilities
- `code/client/pages/Onboarding.tsx` - Onboarding completion notification

### Server Endpoints

- `code/server/index.ts` - Social, community, task, application, moderation, auth endpoints
- `code/api/discord/oauth/callback.ts` - Account linking notifications
- `code/api/_notifications.ts` - Backend notification helper utilities

### Database

- `notifications` table - Stores all notifications
- `user_follows` - Follow notifications
- `community_post_likes` - Like notifications
- `community_comments` - Comment notifications
- `endorsements` - Endorsement notifications
- `mentorship_requests` - Mentorship notifications
- `aethex_applications` - Application notifications
- `project_tasks` - Task notifications
- `moderation_reports` - Moderation notifications
- `game_sessions` - Device login tracking

## Real-Time Features

- **Real-time Updates**: Supabase subscriptions push notifications to NotificationBell instantly
- **Cross-Tab Sync**: Notifications sync across browser tabs and devices
- **WebSocket Based**: Low-latency delivery without polling
- **Unread Tracking**: Badge shows count of unread notifications

## How Notifications Are Created

### Pattern 1: Direct Insert (Server Endpoints)

```javascript
await adminSupabase.from("notifications").insert({
  user_id: targetUserId,
  type: "info",
  title: "Notification Title",
  message: "Notification message",
});
```

### Pattern 2: Service Method (Client Services)

```javascript
await aethexNotificationService.createNotification(
  userId,
  "success",
  "Title",
  "Message",
);
```

### Pattern 3: Trigger Utilities (Client)

```javascript
await notificationTriggers.postLiked(userId, likerName);
```

## Performance Considerations

1. **Non-Blocking**: Notifications don't block main operations
2. **Batch Inserts**: Multiple staff notifications inserted in batch
3. **Lazy Loading**: Only latest 20 notifications fetched initially
4. **Real-Time Subscription**: Efficient WebSocket streaming
5. **Error Handling**: Notification failures don't crash main operation

## Notification Display

**NotificationBell Component** (`code/client/components/notifications/NotificationBell.tsx`)

- Bell icon with unread count badge
- Dropdown showing latest notifications
- Type-specific icons (emoji-based)
- Mark individual or all as read
- Real-time update via Supabase subscription

**Dashboard Tab** (`code/client/pages/Dashboard.tsx`)

- Full notification history
- Type filtering options
- Batch actions (mark as read)

## Testing Notifications

### Manual Testing Checklist

- [ ] Create team/project → notification
- [ ] Get added to team/project → notification
- [ ] Like community post → post author notified
- [ ] Comment on post → post author notified
- [ ] Submit job application → opportunity poster notified
- [ ] Application status changed → applicant notified
- [ ] Assign task → assignee notified
- [ ] New device login → user warned
- [ ] Submit moderation report → staff notified
- [ ] Earn achievement → user notified
- [ ] Level up → user notified
- [ ] Link Discord → user notified

### Database Verification

```sql
-- Check notifications for user
SELECT * FROM notifications
WHERE user_id = '...'
ORDER BY created_at DESC
LIMIT 20;

-- Check notification types
SELECT type, COUNT(*) FROM notifications GROUP BY type;

-- Check unread count
SELECT COUNT(*) FROM notifications
WHERE user_id = '...' AND read = false;
```

## Future Enhancements

- [ ] Daily/weekly digest emails
- [ ] In-app notification center with search
- [ ] Notification preferences/categories
- [ ] Scheduled reminders (task due dates)
- [ ] Batch notifications (15+ activity summary)
- [ ] Push notifications (mobile)
- [ ] Notification templates (customizable text)
- [ ] Notification history export
- [ ] Engagement analytics on notification clicks

## Monitoring

Check in Supabase dashboard:

1. `notifications` table → see all notifications
2. Real-time → verify subscriptions active
3. Database stats → monitor table growth
4. Query performance → check index usage

## Support & Troubleshooting

**Notifications not showing?**

1. Check NotificationBell is rendered in Layout.tsx
2. Verify Supabase subscription in browser console
3. Check notifications table for entries
4. Clear browser cache and reload

**Real-time not working?**

1. Check Supabase realtime enabled
2. Verify WebSocket connection in browser DevTools
3. Check RLS policies allow reading notifications
4. Restart browser and clear session

**Spam notifications?**

1. Check for duplicate inserts
2. Verify notification triggers have `try-catch`
3. Add deduplication logic (check for recent identical notifications)

## Files Summary

| File                                                        | Purpose                             | Lines |
| ----------------------------------------------------------- | ----------------------------------- | ----- |
| `code/server/index.ts`                                      | Server endpoints with notifications | 4800+ |
| `code/client/lib/notification-triggers.ts`                  | Trigger utilities                   | 250+  |
| `code/client/lib/aethex-database-adapter.ts`                | Service notifications               | 2000+ |
| `code/client/components/notifications/NotificationBell.tsx` | UI display                          | 300+  |
| `code/api/_notifications.ts`                                | Backend helpers                     | 40+   |

**Total Notification Triggers: 20+**  
**Notification Types: 4** (success, info, warning, error)  
**Real-time Subscribers: Unlimited**