# 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)

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

### B. Backend Schemas (Task 4)

- [x] **B4.** Create `backend/app/schemas/notification.py`: NotificationResponse, NotificationListResponse, UnreadCountResponse.

### C. Backend Services (Tasks 5–7)

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

### D. Backend API (Tasks 8–10)

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

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

- [x] **E11.** Add `schedule_notification` tool to AI_TOOLS + handler in `_execute_tool` in ai_service.py.
- [x] **E12.** Create `backend/app/workers/notification_sender.py`: periodic job (every 60s) sends pending scheduled notifications via WebSocket.
- [x] **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)

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

### G. Frontend UI (Tasks 17–20)

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

### H. i18n (Task 21)

- [x] **H21.** Update en/ru translations with notification keys.

### I. Tests (Tasks 22–23)

- [x] **I22.** Create `backend/tests/test_notifications.py`: CRUD, mark read, unread count, ownership isolation.
- [x] **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**