# ChangeWatch

> Autonomous public web page monitoring with noise normalization, two-tier SSRF containment, multi-mode visual and text diffs, and serverless Vercel deployment.

ChangeWatch monitors public web pages and alerts users to genuine, meaningful content changes while suppressing ordinary page churn such as timestamps, view counters, dynamic tokens, and ads.

## Core Capabilities
- **Deterministic Noise Normalization**: Systematically sanitizes volatile relative timestamps, ISO 8601 dates, vanity engagement counters, whitespace variations, and dynamic session tokens before SHA-256 fingerprinting.
- **Two-Tier SSRF Defense Fortress**: Pre-navigation DNS resolution blocks RFC 1918 private subnets, IPv6 loopbacks, localhost, link-local, and cloud metadata (169.254.169.254). Playwright Chromium route interception blocks all outgoing subresource requests targeting internal destinations.
- **Visual Region Studio**: Point-and-click selector configuration inside a sandboxed iframe. Supports Watch Scopes (narrow monitoring to specific DOM elements) and Ignore Selectors (strip noise elements before normalization).
- **Multi-Mode Diff Studio**: Line-by-line normalized text diffs (+/-), synchronized side-by-side screenshot comparisons, draggable before/after swipe slider, and Pillow computer vision pixel difference masks.
- **Numeric Tracking & Sparklines**: Extracts numbers, currencies ($, €, £, ₹), percentages, and stock counts from CSS selectors, rendering historical SVG trend sparklines.
- **Keyword-Only Alert Filtering**: Optional trigger keywords (e.g. "in stock", "price drop") that suppress notifications unless matching keywords appear in added lines.
- **Multi-Channel Notification Dispatch**: Rich Discord webhook embeds with pre-rendered diffs, and email dispatches (Console, SMTP, Resend). Webhook secrets encrypted with Fernet at rest.
- **Store-on-Change Policy**: Unchanged checks only record lightweight audit run records; persistent screenshot and DOM artifacts are strictly retained for baselines and genuine changes.

## Architecture & Serverless Deployment
- **Web Runtime**: FastAPI + Jinja2 running on Vercel Python serverless functions.
- **Remote Chromium**: Vercel functions cannot launch local Chromium; they connect to Browserbase CDP sessions (`BROWSERBASE_API_KEY`) or a self-hosted container browser worker (`app/worker_api.py`) exposing authenticated `/internal/capture`.
- **Database**: Managed PostgreSQL (e.g., Neon connection pooling for request runtime + unpooled connection for Alembic migrations via `NEON_DATABASE_URL`). SQLite is supported for local development.
- **Object Storage**: S3-compatible bucket (AWS S3, Cloudflare R2, MinIO) for screenshot and diff image history. If not configured, text comparison operates normally while screenshot storage is gracefully omitted.
- **Background Scheduler**: GitHub Actions workflow (`.github/workflows/monitor-scheduler.yml`) calls `/internal/worker/tick` every 5 minutes with `CRON_SECRET`. Persistent daemons (`workers/scheduler_process.py` and `workers/check_worker.py`) can be run on container hosts for high-volume requirements.

## Contact & Maintainer
- Creator: Aayush Srivastava
- Email: aayush@aayushsrivastava.com
- Documentation: https://changewatch.aayushsrivastava.com/docs
- Privacy Policy: https://changewatch.aayushsrivastava.com/privacy
- Terms of Service: https://changewatch.aayushsrivastava.com/terms
- Contact: https://changewatch.aayushsrivastava.com/contact