How felpau05/grocery-store-deal-tracker works
Grocery-Store-Deal-Tracker collects regional flyer data, normalizes it into searchable deals and price history, and lets shoppers compare prices and plan multi-store trips. The principal flow runs from the browser through the Next.js client and FastAPI routes to Postgres; preference changes can trigger the separate Go scraper, which fetches and parses Flipp data for storage. Python classifies uncategorized scraped items asynchronously. The graph preserves documented auth, cart, history, and optimization capabilities; some frontend and route wiring is based on README descriptions because those sources were not sampled.
Main entry points: main.py FastAPI app · api.ts API client · scrape.go Scrape runner · backfill.py Classification backfill
Components 27
Shopper experience
- Next.js app
frontend/src/app/page.tsx - API client
frontend/src/lib/api.ts - Deals and history
frontend/src/app/deals/page.tsx - Shopping list
frontend/src/app/list/page.tsx - Settings
frontend/src/app/settings/page.tsx
API and accounts
- FastAPI app
backend/main.py - Deal routes
backend/routes/deals.py - Auth and preferences
backend/routes/auth.py - Cart routes
backend/routes/cart.py - Optimization routes
backend/routes/optimize.py - Scraper client
backend/scraper_client.py
Flyer ingestion
- Scraper job API
scraper-go/server.go - Job coordination
scraper-go/job.go - Scrape runner
scraper-go/scrape.go - Flyer fetcher
scraper-go/client.go - Item parser
scraper-go/pipeline.go
Deal data
- Postgres
- Deal and history reads
backend/db/queries.py - Item persistence
backend/db/items.py - Cart persistence
backend/db/cart.py - User persistence
backend/db/users.py
Classification and planning
- Classifier
backend/classifier/classify.py - Classification backfill
backend/classifier/backfill.py - Trip optimizer
backend/optimizer/algorithm.py
Other components
- Shopper
- Flipp API
- Redis
Connections 33
- Shopper → Next.js app: uses
- Next.js app → API client: requests data
- API client → FastAPI app: calls API
- Deals and history → API client: loads deals
- Shopping list → API client: submits list
- Settings → API client: saves preferences
- FastAPI app → Deal routes: registers
- FastAPI app → Auth and preferences: registers
- FastAPI app → Cart routes: registers
- FastAPI app → Optimization routes: registers
- Deal routes → Deal and history reads: queries
- Deal and history reads → Postgres: reads deals and history
- Auth and preferences → User persistence: reads and writes
- User persistence → Postgres: reads and writes
- Cart routes → Cart persistence: reads and writes
- Cart persistence → Postgres: reads and writes
- Auth and preferences → Scraper client: triggers scrape
- Scraper client → Scraper job API: starts and polls jobs
- Scraper client → Redis: caches job IDs
- Scraper job API → Job coordination: claims and tracks
- Job coordination → Redis: locks and stores jobs
- Scraper job API → Scrape runner: runs asynchronously
- Scrape runner → Flyer fetcher: fetches flyer data
- Flyer fetcher → Flipp API: requests flyers and items
- Scrape runner → Item parser: normalizes items
- Scrape runner → Item persistence: persists items
- Item persistence → Postgres: writes items
- Optimization routes → Trip optimizer: optimizes list
- Optimization routes → Deal and history reads: loads deal data
- FastAPI app → Classification backfill: starts scheduler
- Classification backfill → Postgres: reads uncategorized items
- Classification backfill → Classifier: classifies batches
- Classification backfill → Item persistence: updates categories