personal-ai-assistant/plans/phase-5-notifications.md

Phase 5: Notifications — Subplan

Goal

Deliver in-app real-time notifications via WebSocket, APScheduler for scheduled/recurring notifications, AI tool schedule_notification, daily proactive health review job, and frontend notification UI (bell in header, notification list page).

Prerequisites

• Phase 4 completed: memory service, AI tools, document processing
• APScheduler added to dependencies

---

Tasks

A. Backend Model & Migration (Tasks 1–3)

• A1. Create backend/app/models/notification.py: Notification model (user_id, title, body, type, channel, status, scheduled_at, sent_at, read_at, metadata JSONB).
• A2. Add notifications relationship on User model. Update models/__init__.py.
• A3. Create migration 005_create_notifications.py.

B. Backend Schemas (Task 4)

• B4. Create backend/app/schemas/notification.py: NotificationResponse, NotificationListResponse, UnreadCountResponse.

C. Backend Services (Tasks 5–7)

• C5. Create backend/app/services/notification_service.py: create, list, unread count, mark read, mark all read, get pending scheduled, mark sent.
• C6. Create backend/app/services/ws_manager.py: ConnectionManager class (connect, disconnect, send_to_user).
• C7. Create backend/app/services/scheduler_service.py: AsyncIOScheduler wrapper (start, stop, schedule one-time, schedule recurring).

D. Backend API (Tasks 8–10)

• D8. Create backend/app/api/v1/notifications.py: GET list, GET unread-count, PATCH /{id}/read, POST mark-all-read.
• D9. Create backend/app/api/v1/ws.py: WebSocket /ws/notifications with JWT auth via query param.
• D10. Register routers. Wire scheduler in main.py lifespan. Add apscheduler to pyproject.toml.

E. Backend AI Tool + Workers (Tasks 11–13)

• E11. Add schedule_notification tool to AI_TOOLS + handler in _execute_tool in ai_service.py.
• E12. Create backend/app/workers/notification_sender.py: periodic job (every 60s) sends pending scheduled notifications via WebSocket.
• E13. Create backend/app/workers/health_review.py: daily job queries user memories/docs, asks Claude for reminders, creates ai_generated notifications.

F. Frontend API & Store (Tasks 14–16)

• F14. Create frontend/src/api/notifications.ts.
• F15. Create frontend/src/stores/notification-store.ts (Zustand).
• F16. Create frontend/src/hooks/use-notifications-ws.ts: WebSocket with auto-reconnect.

G. Frontend UI (Tasks 17–20)

• G17. Create frontend/src/components/notifications/notification-bell.tsx: bell icon + unread badge + dropdown.
• G18. Integrate bell into header.tsx. Init WebSocket in AppLayout.
• G19. Create frontend/src/pages/notifications.tsx: full list with type filter, mark read.
• G20. Update routes + enable sidebar notifications link.

H. i18n (Task 21)

• H21. Update en/ru translations with notification keys.

I. Tests (Tasks 22–23)

• I22. Create backend/tests/test_notifications.py: CRUD, mark read, unread count, ownership isolation.
• I23. Verify frontend builds cleanly.

---

Acceptance Criteria

1. Notification CRUD API works with auth and ownership isolation
2. WebSocket pushes notifications in real time
3. AI schedule_notification tool creates scheduled/immediate notifications
4. APScheduler fires pending notifications at scheduled_at time
5. Daily health review generates ai_generated notifications
6. Frontend bell shows unread count, dropdown shows recent, updates in real time
7. Notifications page with type filter and mark-as-read
8. All UI text in English and Russian
9. Backend tests pass, frontend builds clean

---

Status

COMPLETED