F-026: Saved Searches with Alerts

Status: 🔨 In Progress · Priority: P1 · Updated: Mar 13, 2026

Summary

Allow authenticated users to save their current search filters and receive notifications (Telegram and/or email) when new listings match. This is the #1 retention driver on rental platforms.

Requirements

• [ ] "Save this search" button on listings browse page (stores current filter params)
• [ ] New saved_searches DB table (userId, filters JSON, notification preferences, last_notified_at)
• [ ] API endpoints: CRUD for saved searches
• [ ] Dashboard page to manage saved searches (view, edit, delete, toggle notifications)
• [ ] Periodic job (hourly): run saved searches against new listings since last check, send alerts
• [ ] Telegram bot notifications (reuse existing scraper Telegram infra)
• [ ] Optional email notifications (future phase)
• [ ] Bilingual (FR/EN) translations
• [ ] Max saved searches per user (e.g., 10)

Design

DB Schema

saved_searches (
  id serial PK,
  user_id int FK users,
  name varchar(100),
  filters jsonb NOT NULL,  -- { neighborhoods, bedrooms, priceMin, priceMax, amenities, ... }
  notify_telegram boolean DEFAULT false,
  notify_email boolean DEFAULT false,
  telegram_chat_id varchar(50),
  last_notified_at timestamp,
  created_at, updated_at
)

API Endpoints

Method	Path	Auth	Description
GET	/saved-searches	Auth	List user's saved searches
POST	/saved-searches	Auth	Create saved search
PUT	/saved-searches/:id	Auth	Update saved search
DELETE	/saved-searches/:id	Auth	Delete saved search

Notification Pipeline

• Hourly periodic job in scraper service (alongside existing staleness/snapshot jobs)
• Query listings created since last_notified_at matching each saved search's filters
• Send grouped notification (Telegram message or email digest)
• Update last_notified_at

Discussion Notes

Mar 6, 2026 — Proposed. Core retention feature. Every competitor (Zillow, Apartments.com, liv.rent, PadMapper) has this. Medium effort due to DB + periodic job + notifications, but reuses existing Telegram infra.

Implementation Notes

To be filled during implementation.