notification-worker — business features

1. What it is

notification-worker is the platform's delivery layer: other services announce that something happened — a module was assigned, a reminder came due, a streak is about to break — and this service decides who should hear about it, writes the message into that person's in-app inbox, and pushes it to their phone through Firebase. It also serves the inbox itself (history, unread badge, read/opened tracking), the admin notification centre, and the device registry that records which phones a person can be reached on.

It is the only Python service in the repo that is not FastAPI: main.py starts a plain aiohttp application (main.py:22-28) and then hands the process to NotificationWorker.run(), so there is no OpenAPI schema, no dependency injection and no /health route. Its health endpoints are /healthz and /readyz (app/routes/api.py:743-744) — different paths from every other service on the platform, and the k8s probes are wired to those two paths specifically (k8s/deployment.yaml:77-88).

2. Feature map

flowchart LR
  MOB["Employee app (off-repo)"] --> INBOX["Devices + notification inbox"]
  ADM["Admin web (off-repo)"] --> ADMIN["Admin inbox + email settings"]
  UA["users-auth-service"] --> INT["Push reachability + GDPR export"]
  AS["assignment-service"] --> TRAIN["Assigned, reminder, overdue, escalation"]
  ML["micro-learning-service-v2"] --> GAME["Streak + leaderboard nudges"]
  FS["feed-service"] --> FEEDN["Feed announcements"]
  INBOX --> HTTP["15 aiohttp routes"]
  ADMIN --> HTTP
  INT --> HTTP
  TRAIN --> NATS["9 MICRO_LEARNING durables"]
  GAME --> NATS
  FEEDN --> NATS
  HTTP --> STORE["notifications + user_devices"]
  NATS --> STORE
  NATS --> FCM["Firebase FCM push"]

3. Features

Admin

Employee (mobile)

Internal (other services)

Background

4. API reference

All 15 routes registered by setup_routes (app/routes/api.py:725-777). "Bearer" = a users-auth JWT validated against JWKS; "X-Oper-Key" = the shared internal key. The admin web app and the mobile app are not in this repo, so a route whose only named caller is a frontend doc is cited to that doc.

5. Async contracts

Consumes

Ten distinct subjects across 11 scanned registrations. For each one the publisher's real subject was compared token-for-token against the consumer's filter, because a token-count mismatch is silent: the consumer is created, reports healthy, and matches nothing. That is exactly the bug that killed reminders and streaks (to-be-reviewed/README.md #1); the fix is _to_filter_subject (app/services/notification_service.py:99-113), which uses a configured subject verbatim when it already contains a wildcard instead of appending .>. All nine live filters now match their publisher's token count.

The scan JSON lists this subject twice. The second entry (app/services/admin_notification_service.py:582) is a scanner mis-attribution: line 582 is the generic _pull_subscribe helper whose subject= is a parameter, and the scanner resolves an unbound subject name from its service-wide constant table (tools/feature-docs/scan.py:298-299), picking up the literal from nats_service.py:47. The helper's real subjects are the three admin settings values at admin_notification_service.py:596-612, each already listed above.

Ops note, not a subject mismatch: the streak and leaderboard consumers bind to MICRO_LEARNING, but this service's own copy of the stream definition omits learning.> and user.notification.> (k8s/nats-screams-cm.yaml:31). The canonical definitions do include them (micro-learning-service-v2/nats/streams/training-modules.json:10, assignment-service/nats/streams/micro-learning.json:10) and this service's init scripts are never executed (§8), so the live stream is correct — known defect ARCHITECTURE.md §4.1(4).

Publishes

Background jobs

No CronJob exists for this service; both jobs are in-process tasks of the single notification-worker Deployment. A SIGTERM rollout skips their graceful stop — known defect bug-hunt-reports/notification-worker.md #10.

6. Data it owns

Postgres logical DB notifications; notification-worker is the only writer (ARCHITECTURE.md §3.4). Four live tables after alembic/versions/drop_unused_tables.py removed the chat-era channel_members and notification_history.

No other service writes into this database, and this service writes into no other database. Everything it needs from elsewhere it fetches over HTTP: learner notification preferences and the tenant's admin list from users-auth (the notification_preferences table lives in users_auth — users-auth-service/app/services/gdpr_export.py:110), and the active-assignment check from assignment-service. Redis db 1 holds only derived state: daily-cap counters and short-TTL caches.

7. Dependencies

flowchart LR
  MOB["Employee app (off-repo)"] --> NW["notification-worker"]
  ADMW["Admin web (off-repo)"] --> NW
  AS["assignment-service (H18)"] --> NW
  UA["users-auth-service (H21, H23)"] --> NW
  ML["micro-learning-service-v2"] -. NATS .-> NW
  FS["feed-service"] -. NATS .-> NW
  AV2["authoring-service-v2"] -. NATS .-> NW
  NW --> UAO["users-auth: admins, preferences (H25)"]
  NW --> ASO["assignment-service: active assignments (H26)"]
  NW --> FCM["Firebase FCM"]
  NW -. "auth.admin.alert" .-> OTP["otp-worker: Mailgun email"]
  NW --> PG["Postgres: notifications"]
  NW --> RD["Redis: db 1"]

8. Dead-code verdicts

Every entry point with no in-repo caller. Deleting is a separate decision — see the hub roll-up.

Everything else in the scan is live: 13 of 15 routes have a named caller or probe, 9 of 10 consumed subjects have a confirmed publisher with a matching token count, the single published subject has a confirmed consumer, and both background tasks are started from NotificationWorker.run(). Open correctness defects that are not dead code — duplicate pushes on JetStream redelivery, deferred pushes mislabelled as reminders, the feed fan-out ack window, the internal API key in a tracked ConfigMap — are tracked in bug-hunt-reports/notification-worker.md and to-be-reviewed/notification-worker.md, not restated here.

9. Sources

• tools/feature-docs/out/notification-worker.json — the scanned entry points this page is checked against.
• ARCHITECTURE.md §2 (inventory), §3.2 (HTTP edges H18, H21, H23, H25, H26), §3.3 (JetStream streams), §3.4 (DB writers), §3.5 (Redis db map), §4.1 (known defects 3 and 4 — note 4.1(3) is stale, see §5).
• bug-hunt-reports/notification-worker.md — 10 findings; #1 (device IDOR) and #4 (blocking FCM send) verified fixed in current code.
• to-be-reviewed/README.md — notification-engine review index and fix log.
• to-be-reviewed/notification-worker.md — per-service findings; N1/N2/N3/N4/N6 and N-A3/N-A5 confirmed fixed, N-A12 (dead NATSService) confirmed still present.
• docs/flutter_notifications_guide.md — mobile caller contract for the inbox routes; the source for the /{id}/read verdict.
• docs/fe-admin-notification-settings.md — admin web caller contract for the admin inbox and settings routes.
• docs/admin_notification_preferences.md — category and email-mirror API/ops reference.
• docs/notification_deeplinks.md — authoritative type → oper:// deep-link mapping.
• docs/assignment_notification_contract.md, docs/NATS_MESSAGE_PUBLISHING.md, docs/QUICK_REFERENCE.md — event payload contracts.
• docs/ARCHITECTURE.md — service-local design doc; partly stale (it still documents NATSService at line 206).
• spec/oper_notification_history_sdd.md — the inbox/history SDD (routes were implemented on aiohttp, not the FastAPI router the SDD sketches).
• spec/notification-worker.md — the original AWS SNS chat-push design; superseded, see §8.
• New-Design/SDD-admin-notification-centre.md, New-Design/PLAN-admin-notif-centre-tier1.md — admin notification centre design and route list.