api/CLAUDE.md

CartSnitch API Gateway

Project Context

CartSnitch is a self-hosted grocery price intelligence platform built as a polyrepo microservices architecture. This repo (cartsnitch/api) is the public-facing API gateway that serves the frontend and proxies requests to internal services.

GitHub org: github.com/cartsnitch Domain: cartsnitch.com

CartSnitch Services

Repo	Service	Purpose
cartsnitch/common	—	Shared models, schemas, utilities
cartsnitch/receiptwitness	ReceiptWitness	Purchase data ingestion via retailer scrapers
cartsnitch/api	API Gateway	Frontend-facing REST API (this repo)
cartsnitch/cartsnitch	Frontend	React PWA (mobile-first)
cartsnitch/stickershock	StickerShock	Price increase detection & CPI comparison
cartsnitch/shrinkray	ShrinkRay	Shrinkflation monitoring
cartsnitch/clipartist	ClipArtist	Coupon/deal watching & shopping optimization
cartsnitch/infra	—	K8s manifests, Flux kustomizations

Architecture Decisions

• Polyrepo: Each service has its own repo, Dockerfile, CI/CD pipeline.
• Shared DB: One PostgreSQL cluster. This service reads from all tables for serving frontend queries. The API has its own local SQLAlchemy models — it does NOT import from cartsnitch-common.
• Inter-service comms: REST to internal services, Redis pub/sub for event subscriptions.
• Target scale: 500–1,000 users initially.

What This Service Does

The API Gateway is the single entry point for the frontend PWA and any external consumers. It:

1. Handles user authentication — registration, login, JWT token management
2. Serves purchase/product/price data — reads from the shared DB
3. Proxies scraping operations — forwards scrape triggers to ReceiptWitness
4. Serves coupon/deal data — reads from shared DB (written by ClipArtist)
5. Serves alerts — price increase alerts (StickerShock), shrinkflation alerts (ShrinkRay)
6. Provides public data endpoints — aggregate price trends for the transparency/shaming features

Tech Stack

• Python 3.12+
• FastAPI (async)
• SQLAlchemy 2.0 (async, read-heavy)
• Pydantic v2 (request/response validation)
• python-jose or PyJWT (JWT auth)
• passlib + bcrypt (password hashing)
• httpx (async HTTP client for proxying to internal services)
• Redis (subscribe to events for websocket push, caching)
• uvicorn (ASGI server)

Repo Structure

api/
├── CLAUDE.md
├── README.md
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── src/
│   └── cartsnitch_api/
│       ├── __init__.py
│       ├── config.py           # Service-specific settings
│       ├── main.py             # FastAPI app factory, lifespan, middleware
│       ├── auth/
│       │   ├── __init__.py
│       │   ├── jwt.py          # JWT creation/validation
│       │   ├── passwords.py    # Hashing, verification
│       │   ├── dependencies.py # FastAPI dependency injection (get_current_user)
│       │   └── routes.py       # /auth/register, /auth/login, /auth/refresh
│       ├── routes/
│       │   ├── __init__.py
│       │   ├── purchases.py    # Purchase history endpoints
│       │   ├── products.py     # Normalized product catalog
│       │   ├── prices.py       # Price history and trends
│       │   ├── coupons.py      # Active coupons and deals
│       │   ├── alerts.py       # Price increase / shrinkflation alerts
│       │   ├── stores.py       # Store info, user store account management
│       │   ├── scraping.py     # Proxy to ReceiptWitness (trigger scrape, status)
│       │   ├── shopping.py     # Optimized shopping list (proxy to ClipArtist)
│       │   ├── public.py       # Public price transparency endpoints (no auth)
│       │   └── health.py
│       ├── services/
│       │   ├── __init__.py
│       │   ├── receiptwitness.py   # HTTP client for ReceiptWitness internal API
│       │   ├── stickershock.py     # HTTP client for StickerShock internal API
│       │   ├── clipartist.py       # HTTP client for ClipArtist internal API
│       │   └── shrinkray.py        # HTTP client for ShrinkRay internal API
│       ├── middleware/
│       │   ├── __init__.py
│       │   ├── cors.py
│       │   └── rate_limit.py
│       └── cache.py            # Redis caching helpers
└── tests/
    ├── conftest.py
    ├── test_auth/
    ├── test_routes/
    └── test_services/

API Endpoint Design

Auth

• POST /auth/register — create account
• POST /auth/login — get JWT access + refresh tokens
• POST /auth/refresh — refresh access token
• GET /auth/me — current user profile

Store Accounts

• GET /stores — list supported stores
• GET /me/stores — list user's connected store accounts + sync status
• POST /me/stores/{store_slug}/connect — initiate store connection flow
• DELETE /me/stores/{store_slug} — disconnect store account

Purchases

• GET /purchases — list user's purchases (paginated, filterable by store/date)
• GET /purchases/{id} — purchase detail with line items
• GET /purchases/stats — spending summary (by store, by category, by period)

Products

• GET /products — normalized product catalog (search, filter)
• GET /products/{id} — product detail with cross-store price comparison
• GET /products/{id}/prices — price history for a product across stores

Prices

• GET /prices/trends — aggregate price trends (public-capable)
• GET /prices/increases — recent significant price increases
• GET /prices/comparison — compare specific items across stores

Coupons

• GET /coupons — active coupons/deals (filterable by store)
• GET /coupons/relevant — coupons relevant to user's purchase history

Shopping

• POST /shopping/optimize — input: shopping list → output: store-split + coupons
• GET /shopping/lists — user's saved shopping lists

Alerts

• GET /alerts — user's price increase and shrinkflation alerts
• PUT /alerts/settings — configure alert thresholds

Public (No Auth)

• GET /public/trends/{product_id} — public price trend for a product
• GET /public/store-comparison — public store-vs-store price comparison
• GET /public/inflation — price changes vs CPI baseline

Scraping (Proxy to ReceiptWitness)

• POST /scraping/{store_slug}/sync — trigger a sync for the current user
• GET /scraping/status — sync status across all stores

Authentication

• JWT-based auth with short-lived access tokens (15 min) and longer refresh tokens (7 days).
• Passwords hashed with bcrypt via passlib.
• All user-specific endpoints require a valid JWT in the Authorization: Bearer header.
• Public endpoints under /public/ do not require auth.
• Internal service-to-service calls (ReceiptWitness, etc.) use a shared API key in the X-Service-Key header — not user JWTs.

Development Workflow

• Never push directly to main. Always create feature branches and open PRs.
• Branch naming: feature/<description> or fix/<description>
• Use conventional commits: feat:, fix:, refactor:, docs:, chore:
• OpenAPI docs auto-generated at /docs (Swagger) and /redoc.
• Write tests for all routes. Use httpx.AsyncClient with FastAPI's TestClient pattern.

Important Notes

• This service is read-heavy on the shared DB. Use async SQLAlchemy sessions.
• Consider Redis caching for expensive queries (price trends, product comparisons). Cache invalidation via Redis pub/sub events from other services.
• Rate limiting on public endpoints is important — these could get hammered if the price transparency features get attention.
• CORS must allow the frontend origin (cartsnitch.com and localhost for dev).
• The store connection flow is the trickiest UX challenge: the user needs to authenticate with each retailer, and we need to capture the resulting session. This likely involves a controlled Playwright browser session that the user can see/interact with, or an OAuth-like redirect flow if the retailer supports it (Kroger does for its public API, but not for purchase history access).