feat: Notifier Service — watchlists and alerts for new music data

[SimplicityGuy]

Overview

Users can currently sync their Discogs collection via OAuth, but they receive no feedback when the monthly data import brings in new releases, new information about watched artists, or changes to their areas of interest. A Notifier Service adds watchlists and push/webhook notifications to close this loop.

Motivation

The monthly Discogs data dump cycle is the heartbeat of the platform. Graphinator and Tableinator process 15M+ releases each cycle, but this work is invisible to end users. A notification layer transforms the platform from a passive query tool into one that actively surfaces new information relevant to each user.

Proposed Features

Watchlists

Users can watch any entity in the graph:

• Artist — notify when new releases appear, or when the artist gains new aliases/members
• Label — notify when new releases are published on the label
• Genre/Style — notify when release count crosses a threshold or notable new releases appear
• Search query — notify when new entities match a saved search

Watchlists are stored in PostgreSQL per user and managed via the API.

Notification Channels

• In-app feed: GET /api/notifications returns paginated notification history; POST /api/notifications/{id}/read marks as read
• Webhook: user configures a URL; Notifier POSTs a JSON payload on each event
• Email (optional / future): pluggable delivery backend, initially disabled

Notification Triggers

After each import cycle completes (Graphinator + Tableinator both signal done via a RabbitMQ completion message):

1. Notifier queries watched entities for each user
2. Compares current graph state against the last-seen snapshot (stored in PostgreSQL)
3. Generates notification records for any differences
4. Dispatches via configured channels

Architecture

• New service: notifier/ — FastAPI app with a background task listener
• Trigger: subscribes to a RabbitMQ import.completed exchange (new exchange, published by Graphinator/Tableinator when a full cycle finishes)
• Storage:
  • notifier.watchlists — user_id, entity_type, entity_id, created_at
  • notifier.notification_events — user_id, entity_type, entity_id, event_type, payload JSONB, sent_at, read_at
  • notifier.webhook_configs — user_id, url, secret (for HMAC signing), active
• Health: standard health endpoint at port 8010
• API endpoints (authenticated):
  • GET /api/watchlist — list watched entities
  • POST /api/watchlist — add entity to watchlist
  • DELETE /api/watchlist/{id} — remove from watchlist
  • GET /api/notifications — paginated notification feed
  • POST /api/notifications/read-all — mark all read
  • POST /api/webhook — configure webhook URL
  • DELETE /api/webhook — remove webhook

Webhook Payload Example

{
  "event": "new_releases",
  "entity_type": "artist",
  "entity_id": "artist-123",
  "entity_name": "John Coltrane",
  "detail": {
    "new_release_count": 3,
    "release_ids": ["r-456", "r-789", "r-1011"]
  },
  "timestamp": "2026-02-01T00:00:00Z"
}

HMAC-SHA256 signature sent in X-Discogsography-Signature header for webhook verification.

Import Completion Signal

Graphinator and Tableinator each publish a message to import.completed exchange when they finish processing a data dump. Notifier only fires after both signal completion (tracked with a simple counter in Redis).

Acceptance Criteria

• Users can watch artists, labels, genres, and styles via the API
• Notifications are generated within 10 minutes of an import cycle completing
• In-app notification feed is paginated and supports mark-as-read
• Webhook delivery includes HMAC signature; retries 3 times with exponential backoff on failure
• Watchlist changes take effect for the next import cycle (no retroactive notifications)
• Service follows container hardening standards
• Unit tests for diff logic and webhook dispatch; integration tests against seeded data
• Coverage ≥ 80%

[SimplicityGuy]

Update: The curator/curator.py file referenced in this issue no longer exists. Sync logic has moved to api/routers/sync.py and api/syncer.py. The Insights service (#85, now merged) could serve as a notification trigger source.

[SimplicityGuy]

Status Update — 2026-03-25

Not started. No implementation or design work has been merged to main for this feature.