Recommendations API

Proposal for a lightweight recs service backing the Cart empty-state PRD (delta #7). Reviewers must sign off before it becomes a delta.

Motivation

We need a single endpoint that returns 3 relevant products given a user (or a session cookie for anonymous users). Latency budget p95 < 200ms.

Proposal

Serve from an in-process cache backed by an offline job that recomputes hourly. First cut is "recently-viewed of the same session" — no ML, no vector store. GET /api/recs?context=cart&limit=3 returns { items: [{ id, title, price, image_url }, ...] }.

Alternatives considered

• Third-party (Algolia Recommend) — fastest to build; adds a vendor and a per-query cost.
• Real-time vector store (pgvector) — best relevance; too much infra for a v1.
• Static "popular items" — cheapest; ignores user intent entirely.

Open questions

• How do we invalidate the cache when stock hits zero?
• Do we log recs impressions server-side or client-side?