Coupette

Wine discovery and recommendation platform. Data sourced from the SAQ (Quebec liquor board) catalog.

FastAPI · PostgreSQL + pgvector · Claude API · React · Docker

• 💬 AI sommelier — intent routing, hybrid search, and conversational recommendations via Claude + pgvector
• 🍷 ~14k wine products scraped from the SAQ public sitemap into PostgreSQL
• 🔍 Catalog API with faceted search, filtering, and restock alerts
• 📍 In-store availability for Montreal stores (daily refresh via SAQ's catalog API)
• 🤖 Telegram bot for restock/destock alerts
• 🌐 Web app at coupette.club (React + Vite)

Architecture

graph LR
    SAQ[SAQ.com]
    Adobe[Adobe Live Search]
    Scraper[Scraper]
    DB[(PostgreSQL + pgvector)]
    API[FastAPI]
    Claude[Claude API]
    Bot[Telegram Bot]
    Web[React Frontend]

    SAQ -- sitemap XML --> Scraper
    Adobe -- store availability --> Scraper
    Scraper -- write --> DB
    DB -- read --> API
    API -- context --> Claude
    Claude -- recommendations --> API
    Bot -- calls --> API
    Web -- calls --> API

Loading

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 setup and local workflow.

Documentation

• Architecture — system design, schema boundaries, key decisions
• Development & Operations — cold start, infra coupling, deploy, scraper ops, migrations
• Security — auth model, threat model, CI scanning
• Engineering — testing, observability, SRE, ML/MLOps
• Scaling — performance journey: measure, optimize, scale up, scale out
• Product Vision — positioning, core loop, monetization hypotheses
• Roadmap — product phases
• Decisions — ADRs for key technical choices
• Changelog — release history

Specs: Auth System · Chat System · Data Pipeline · Recommendations · Telegram Bot

Legal

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