A self-hostable web app that watches retailer listing pages and pushes Gotify alerts when products come into stock. It distinguishes a pre-public early-access buyable window from full public availability, and surfaces a one-tap add-to-basket link where the store exposes one.
- 3-phase stock model — out-of-stock / early-access / public-availability, with a configurable early-access window (
EARLY_ACCESS_DAYS) - Add-to-basket deep links — where a store exposes a direct-add link, early-access alerts carry a 🛒 one-tap buy link before the item is public
- Pluggable store handlers — ships with AO.com and John Lewis listing-page parsers; add new stores by dropping in a
SiteHandlersubclass - Cloudflare-resilient fetching —
curl_cffibrowser impersonation to get past TLS/HTTP2-fingerprint bot walls - Delivery-safe Gotify notifications — a transition is recorded only if its push is delivered, so a restock is never silently lost
- Stock history — reconstructs each product's buyable episodes (in → out, how long, early-access lead) from the event log
- Per-watch scraping health — tracks consecutive failures and alerts once (not per tick), with a recovery notice
- React dashboard + settings UI — manage watches, preview matches live, view history, and configure alerts from a browser
| Layer | Technology |
|---|---|
| Backend | FastAPI · async SQLAlchemy 2 / SQLite · APScheduler |
| Frontend | React 19 · Vite · Tailwind CSS · nginx |
| Deploy | Docker Compose (two services) |
cp .env.example .env
# Edit .env — set a 32+ character APP_SECRET_KEY (openssl rand -hex 32)
# Optionally set GOTIFY_URL / GOTIFY_TOKEN and SEED_*_URL
docker compose up -d --buildThe UI is available at http://localhost:${FRONTEND_PORT:-9181}. Add watches
via the Watches tab (the first visit asks you to create your account, so do that straight away; set COOKIE_SECURE=false in .env if you serve over plain HTTP). Full walkthrough in docs/setup.md.
- Installation — prerequisites,
.env, environment variable reference - Build & local dev — image builds, running from source, the check CLI, tests, pre-commit
- Deployment & operations — deploy, remote Docker hosts, data persistence, backups, updates, monitoring
- First-run setup — adding watches, the 3-phase model, Gotify, history, adding a store
- Architecture — how it fits together: the stock model, delivery-safety, episode reconstruction, data model
- Plugins: add or replace store handlers from a mounted folder, without rebuilding the image
- The Gotify token is encrypted at rest using Fernet, keyed by
APP_SECRET_KEY. Passwords are hashed with argon2id and API tokens are stored only as hashes. - No secrets in the repository — only
.env.examplewith blank placeholders. - Pre-commit hooks: gitleaks, bandit, ruff, and a custom hook that forbids LAN IP literals from being committed.
- Sign in is built in: the first visit creates the single user (do this straight after installing), sessions use signed
HttpOnlycookies with CSRF protection, and HTTPS is expected (a plain HTTP install must setCOOKIE_SECURE=false). - Other services can read a short allowlist of
GETendpoints with read only API tokens (Settings > API tokens). See deployment. APP_SECRET_KEYalso signs sessions: rotating it signs everyone out and invalidates the stored Gotify token.
MIT — see LICENSE.