SAQ Sommelier

AI-powered wine recommendation engine built on the SAQ (Quebec liquor board) product catalog.

• 🍷 Scrapes ~38k products from the SAQ public sitemap into PostgreSQL
• 🔍 FastAPI catalog API with search, filtering, and restock alerts
• 🤖 Telegram bot for browsing, watching, and notifications
• 📍 In-store availability lookup (planned)
• 💬 Natural language recommendations via Claude RAG (planned)

Architecture

graph LR
    SAQ[SAQ.com]
    Scraper[Scraper]
    DB[(PostgreSQL)]
    API[FastAPI]
    Claude[Claude API]
    Bot[Telegram Bot]
    Web[React Dashboard]

    SAQ -- sitemap XML --> Scraper
    Scraper -- write --> DB
    DB -- read --> API
    API --> Claude
    Bot -- calls --> API
    Web -- calls --> API

    style Web stroke-dasharray: 5 5
    style Claude stroke-dasharray: 5 5

Loading

Dashed = planned. See docs/ARCHITECTURE.md for full details.

Quick start

make install              # install all dependencies (Poetry)
cp .env.example .env      # defaults work as-is
make run-db               # start PostgreSQL (localhost:5432)
make migrate              # create database tables
make dev-scraper          # populate the database (~38k products)
make dev-backend          # start the backend (localhost:8001)

Development

make lint          # ruff check
make format        # ruff format
make test          # pytest (all services)
make coverage      # tests + coverage badges
make migrate       # alembic upgrade head
make build         # docker build
make run / down    # docker compose (full stack / stop)

See docs/DEVELOPMENT.md for database setup options and full workflow.

Documentation

• Architecture — system design, project structure, tech decisions
• Data Flow — three-schema boundary design
• Development — database setup, environment config, dev workflow
• Migrations — Alembic setup, workflow, and troubleshooting
• Scraper Operations — production scheduling, failure recovery, logging
• Store Availability — SAQ AJAX endpoints, store directory, stock checks
• Telegram Bot — bot design, commands, API dependencies
• Roadmap — project phases, discipline roadmaps, and timeline
• Changelog — release history

Legal

SAQ data is scraped ethically via their public sitemap (listed in robots.txt). Rate-limited to 2s between requests with transparent bot identification.

License

MIT