Notifications Advanced Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use compose:subagent (recommended) or compose:execute to implement this plan task-by-task.

Goal: Enhance notification system with full preferences management, notification center, and real-time polling.

Architecture: Three media (in_app, push, mobile). Nine notification types with per-medium toggles. Per-space choices (all/never/mention). Polling for new notifications.

Tech Stack: React 19, TanStack Router, TanStack React Query, shadcn/ui

---

File Structure

src/
├── lib/api/
│   └── notifications.ts                # Enhanced notification API hooks
├── components/notifications/
│   ├── NotificationCenter.tsx          # Full notification center page
│   ├── NotificationItem.tsx            # Single notification row
│   ├── NotificationPreferences.tsx     # Per-medium + per-type toggles
│   └── SpaceNotificationPrefs.tsx      # Per-space preference rows
├── routes/
│   ├── notifications.tsx               # Notification center page
│   └── settings/
│       └── notifications.tsx           # Enhanced settings page

---

Task 1: Enhanced Notification API Hooks

Files:

• Create: src/lib/api/notifications.ts

• [ ] Step 1: Create notification API layer

Hooks to create:

• useNotificationsList(params) — GET /api/headless/v1/notifications with page, sort, status filters

• useNotificationPreferencesFull(medium) — GET /api/headless/v1/notification_preferences/

• useUpdateNotificationPreference(medium) — PUT /api/headless/v1/notification_preferences/

• useUpdateAllSpacePreferences(medium) — PUT /api/headless/v1/notification_preferences/{medium}/spaces

• useUpdateSpacePreference(medium) — PUT /api/headless/v1/notification_preferences/{medium}/spaces/

• usePollNotifications() — refetch new_notifications_count every 30s

• useDeleteNotification() — DELETE /api/headless/v1/notifications/

• [ ] Step 2: Commit

---

Task 2: NotificationItem Component

Files:

• Create: src/components/notifications/NotificationItem.tsx

• [ ] Step 1: Create notification row

Renders a single notification with:

• Actor avatar (gradient fallback)

• Action text using notification_text_structure

• Notifiable title (linked to action_web_url)

• Relative timestamp

• Unread indicator (dot)

• Actions: mark as read, archive, delete (on hover)

• Space badge

• [ ] Step 2: Commit

---

Task 3: NotificationCenter Component

Files:

• Create: src/components/notifications/NotificationCenter.tsx

• [ ] Step 1: Create notification center

Full-page notification list with:

• Header with "Marcar todas como lidas" button

• Filter tabs: Todas, Não lidas, Lidas

• Paginated list using NotificationItem

• Empty state

• Loading skeleton

• Mark all as read mutation

• Delete/archive individual notifications

• [ ] Step 2: Commit

---

Task 4: NotificationPreferences Component

Files:

• Create: src/components/notifications/NotificationPreferences.tsx

• [ ] Step 1: Create preferences panel

For each medium (in_app, push, mobile):

• Global enable/disable toggle

• Per-type toggles:

  • Comentários nos meus posts
  • Respostas aos meus comentários
  • Menções
  • Mensagens diretas
  • Curtidas nos meus posts
  • Curtidas nos meus comentários
  • Lives
  • Novo conteúdo de cursos
  • Enquetes

• Save button per section

• [ ] Step 2: Commit

---

Task 5: SpaceNotificationPrefs Component

Files:

• Create: src/components/notifications/SpaceNotificationPrefs.tsx

• [ ] Step 1: Create per-space preference rows

For each space the user belongs to:

• Space name + emoji

• Choice selector: Todos / Menções / Nunca

• Per-medium columns (in_app, push)

• "Atualizar todos" bulk button

• [ ] Step 2: Commit

---

Task 6: Notifications Page Route

Files:

• Create: src/routes/notifications.tsx

• [ ] Step 1: Create notifications page

Standard shell layout (TopBar, Sidebar, MobileBottomNav) with NotificationCenter as main content.

• [ ] Step 2: Commit

---

Task 7: Enhanced Settings Page

Files:

• Modify: src/routes/settings/notifications.tsx

• [ ] Step 1: Update settings page

Replace the current basic MediumSection with the new NotificationPreferences and SpaceNotificationPrefs components. Add in_app medium.

• [ ] Step 2: Commit

---

Task 8: Polling + Badge Updates

Files:

• Modify: src/components/circle/TopBar.tsx

• [ ] Step 1: Add notification polling

Use usePollNotifications() in TopBar to refetch badge count every 30s. Update the notification dropdown to use the enhanced list.

• [ ] Step 2: Commit

---

Task 9: Verify Build

• [ ] Step 1: Run typecheck
• [ ] Step 2: Run build
• [ ] Step 3: Fix any issues