ShopMind - Your brain. Our AI. Better buys.

Existing alternatives

• Retailer-native recommendations (Amazon, Walmart, Target): siloed to one retailer; limited cross-category personalization; weak explainability.
• Price trackers (Honey, CamelCamelCamel): price-centric; no deep preference model; limited proactive planning.
• Shopping assistants / chatbots: often generic LLM wrappers; no durable memory; poor grounding in real product data.
• Personal finance/budget apps: track spend but don’t translate into actionable shopping decisions.

Why they are insufficient

• Data fragmentation: purchases and preferences are spread across retailers, devices, and channels.
• Cold-start + shallow personalization: most systems optimize for immediate conversion, not long-term user fit.
• No durable “taste memory”: users repeat constraints (sizes, brands, allergies, aesthetics) constantly.
• Low trust: unclear why something is recommended; affiliate incentives are opaque.
• High friction checkout: redirects, multiple logins, repeated address/payment entry.

Pain points

• Users waste time searching, comparing, and re-buying essentials.
• Users miss price drops and buy at suboptimal times.
• Users struggle to buy gifts and plan for life events.
• Users don’t want to manage multiple apps for lists, budgets, and shopping.

Market inefficiencies

• Recommendation quality is limited by retailer silos.
• Consumers lack a personal “shopping OS” that persists across contexts.
• Product discovery is noisy; high cognitive load for routine purchases.

Primary persona: Busy online shopper (consumer)

• Age: 25–45
• Shops online weekly; uses Amazon/Target/Instacart-like services
• Values time savings, good deals, and reduced decision fatigue
• Comfortable with chat interfaces

Secondary persona: Deal-conscious planner

• Tracks prices, uses wishlists, buys during sales
• Wants alerts and timing recommendations

Technical maturity

• Low to medium. Must work without technical setup.
• Will connect accounts if trust is established and value is immediate.

Buying behavior (SaaS)

• Freemium expected.
• Will pay if:
• saves measurable time (e.g., replenishment + one-tap reorder)
• saves money (price drop alerts, better substitutions)
• reduces stress (gift planning, event preparation)
• Likely to start with free tier; convert after 1–2 “wins” (caught a price drop, nailed a gift, simplified recurring buys).

MVP scope (buildable in 6–10 weeks)

1) Account + onboarding

• Email/password + OAuth (Google)
• Preference capture:
• sizes (clothing/shoes)
• favorite brands
• dietary restrictions/allergies
• budget ranges by category
• shipping preferences

2) Conversational assistant (web)

• Chat UI with:
• streaming responses
• message citations (“based on your saved preferences / past purchases”)
• quick actions: Save item, Track price, Add to wishlist

3) Product ingestion + search

• Integrate one product source for MVP:
• Option A: Amazon Product Advertising API (if eligible)
• Option B: curated affiliate feed (Impact/Rakuten) or a product dataset API
• Option C: start with a limited set of retailers via a third-party product search API
• Store normalized product records (title, brand, price, images, URL, category, attributes)
• Search endpoint with filters (price range, brand, category)

4) Ranking + personalization

• Baseline ranker:
• lexical + embedding retrieval (hybrid)
• rerank using user preferences (brand affinity, budget fit, constraints)
• “Why this” explanation generator:
• e.g., “Matches your budget under $50 and your preference for minimalist style; similar to your previous purchase.”

5) Wishlist + price tracking

• Wishlist items with target price
• Scheduled price checks (e.g., every 6–12 hours)
• Notifications (email + in-app)

6) Replenishment reminders (lightweight)

• User marks an item as consumable + cadence (e.g., 30 days)
• Reminder notifications

7) Privacy + controls

• Data sources toggles (store chat history, store purchase history)
• Delete conversation / delete account

Explicitly out of MVP

• In-chat checkout across retailers (complex compliance + payments)
• WhatsApp/iMessage (requires platform approvals)
• Automated retailer account linking (Plaid-like for commerce is non-trivial)
• Mood detection beyond simple sentiment tagging

High-level components

• Web App (Next.js): chat UI, wishlist, settings, onboarding
• API Backend (FastAPI): auth, chat orchestration, product search, wishlist, price tracking
• LLM Orchestrator:
• prompt templates
• tool calling (search, wishlist ops)
• memory summarization
• Data Layer:
• Postgres for core entities
• Vector store (pgvector) for embeddings (products + user memory)
• Workers:
• price tracking scheduler
• notification sender
• External services:
• LLM provider (OpenAI/Anthropic)
• Email (Postmark/SendGrid)
• Product data API/feed

Deployment approach

• Containerized services (Docker)
• Single repo monorepo (web + api)
• Deploy on:
• Fly.io/Render for API + workers
• Vercel for Next.js
• Managed Postgres (Neon/Supabase)

Mermaid diagram

flowchart LR
  U[User] -->|Browser| W[Next.js Web App]
  W -->|HTTPS JWT| A[FastAPI Backend]

  A --> P[(Postgres + pgvector)]
  A --> L[LLM Provider]
  A --> S[Product Source API/Feed]

  A --> Q[Job Queue]
  Q --> WK[Worker: Price Tracker]
  Q --> NW[Worker: Notifications]

  WK --> S
  WK --> P
  NW --> E[Email Provider]
  NW --> P

Key implementation notes

• Use tool-calling: LLM decides when to call search_products, add_to_wishlist, set_price_alert.
• Maintain two memory layers:
• short-term: last N messages
• long-term: summarized user profile + embeddings of key preferences

Core schema (Postgres)

users

CREATE TABLE users (
  id UUID PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT,
  oauth_provider TEXT,
  oauth_subject TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_users_email ON users(email);

user_profiles

Stores explicit preferences + derived traits.

CREATE TABLE user_profiles (
  user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
  display_name TEXT,
  locale TEXT DEFAULT 'en-US',
  currency TEXT DEFAULT 'USD',
  sizes JSONB DEFAULT '{}'::jsonb,
  dietary JSONB DEFAULT '{}'::jsonb,
  brand_affinities JSONB DEFAULT '{}'::jsonb,
  category_budgets JSONB DEFAULT '{}'::jsonb,
  privacy_settings JSONB DEFAULT '{}'::jsonb,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

conversations + messages

CREATE TABLE conversations (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  title TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_conversations_user ON conversations(user_id, created_at DESC);

CREATE TABLE messages (
  id UUID PRIMARY KEY,
  conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
  role TEXT NOT NULL CHECK (role IN ('user','assistant','tool')),
  content TEXT NOT NULL,
  tool_name TEXT,
  tool_payload JSONB,
  sentiment TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_messages_conv ON messages(conversation_id, created_at);

products

Normalized product catalog.

CREATE TABLE products (
  id UUID PRIMARY KEY,
  source TEXT NOT NULL,
  source_product_id TEXT NOT NULL,
  url TEXT NOT NULL,
  title TEXT NOT NULL,
  brand TEXT,
  category TEXT,
  description TEXT,
  image_url TEXT,
  attributes JSONB DEFAULT '{}'::jsonb,
  current_price_cents INT,
  currency TEXT DEFAULT 'USD',
  last_seen_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE(source, source_product_id)
);
CREATE INDEX idx_products_source_id ON products(source, source_product_id);
CREATE INDEX idx_products_category ON products(category);
CREATE INDEX idx_products_brand ON products(brand);

product_prices

CREATE TABLE product_prices (
  id UUID PRIMARY KEY,
  product_id UUID NOT NULL REFERENCES products(id) ON DELETE CASCADE,
  price_cents INT NOT NULL,
  currency TEXT NOT NULL,
  checked_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_prices_product_time ON product_prices(product_id, checked_at DESC);

wishlists + wishlist_items

CREATE TABLE wishlists (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  name TEXT NOT NULL DEFAULT 'Default',
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_wishlists_user ON wishlists(user_id);

CREATE TABLE wishlist_items (
  id UUID PRIMARY KEY,
  wishlist_id UUID NOT NULL REFERENCES wishlists(id) ON DELETE CASCADE,
  product_id UUID NOT NULL REFERENCES products(id) ON DELETE CASCADE,
  target_price_cents INT,
  track_price BOOLEAN NOT NULL DEFAULT true,
  notes TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE(wishlist_id, product_id)
);
CREATE INDEX idx_wishlist_items_track ON wishlist_items(track_price) WHERE track_price = true;

replenishments

CREATE TABLE replenishments (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  product_id UUID REFERENCES products(id) ON DELETE SET NULL,
  label TEXT NOT NULL,
  cadence_days INT NOT NULL,
  last_purchased_at TIMESTAMPTZ,
  next_due_at TIMESTAMPTZ,
  active BOOLEAN NOT NULL DEFAULT true,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_replenishments_due ON replenishments(next_due_at) WHERE active = true;

embeddings (pgvector)

-- requires pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE product_embeddings (
  product_id UUID PRIMARY KEY REFERENCES products(id) ON DELETE CASCADE,
  embedding vector(1536),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_product_embeddings_vec ON product_embeddings USING ivfflat (embedding vector_cosine_ops);

CREATE TABLE user_memory_embeddings (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  kind TEXT NOT NULL, -- e.g., 'preference','constraint','summary'
  content TEXT NOT NULL,
  embedding vector(1536),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_user_memory_user ON user_memory_embeddings(user_id, created_at DESC);
CREATE INDEX idx_user_memory_vec ON user_memory_embeddings USING ivfflat (embedding vector_cosine_ops);

Auth

• JWT access token (short-lived) + refresh token (httpOnly cookie)
• OAuth optional (Google)

Core endpoints (FastAPI)

Auth

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/refresh
• POST /v1/auth/logout

Profile

• GET /v1/me
• PATCH /v1/me/profile

Chat

• POST /v1/conversations
• GET /v1/conversations
• GET /v1/conversations/{id}
• POST /v1/conversations/{id}/messages (streaming)

Request (send message)

{ "content": "I need running shoes under $120 for wide feet." }

Response (SSE stream)

• event: token (assistant tokens)
• event: tool_call (search invocation)
• event: final (final assistant message + product cards)

Products

• GET /v1/products/search?q=...&category=...&min_price=...&max_price=...
• GET /v1/products/{id}

Response (search)

{
  "results": [
    {
      "product_id": "...",
      "title": "...",
      "brand": "...",
      "price_cents": 9999,
      "currency": "USD",
      "url": "...",
      "image_url": "...",
      "score": 0.82,
      "reasons": ["Matches your budget", "Brand you like"]
    }
  ]
}

Wishlist

• POST /v1/wishlists
• GET /v1/wishlists
• POST /v1/wishlists/{id}/items
• PATCH /v1/wishlists/{id}/items/{item_id} (target price, track toggle)
• DELETE /v1/wishlists/{id}/items/{item_id}

Price tracking

• GET /v1/price-alerts (derived from wishlist_items where track_price=true)

Replenishment

• POST /v1/replenishments
• GET /v1/replenishments
• PATCH /v1/replenishments/{id}
• DELETE /v1/replenishments/{id}

Tool-calling contract (internal)

Define tools exposed to LLM:

• search_products(query, filters)
• get_user_profile()
• add_to_wishlist(product_id, wishlist_id, target_price_cents)
• set_replenishment(product_id|label, cadence_days)
• explain_recommendation(product_id) (optional; can be generated inline)

Recommended stack

Frontend

• Next.js (App Router) + TypeScript
• Fast iteration, SSR for SEO landing pages, strong ecosystem.
• UI: TailwindCSS + shadcn/ui
• Chat streaming: SSE via fetch + readable streams

Backend

• FastAPI + Python
• Great for AI orchestration, typing via Pydantic, async support.
• Background jobs: Celery + Redis (or RQ)
• Needed for scheduled price checks + notifications.

Database

• Postgres + pgvector
• Single durable store for relational + embeddings.

LLM

• Start: OpenAI (Responses API) or Anthropic
• Tool calling + reliable structured outputs.
• Embeddings: text-embedding-3-large (or equivalent)

Hosting

• Vercel for Next.js
• Render/Fly.io for FastAPI + workers
• Neon/Supabase for managed Postgres

Optional alternatives

• Backend in Node (NestJS) if team is TS-only.
• Queue: Cloud Tasks (GCP) or SQS (AWS) for managed scheduling.
• Vector DB: Pinecone if you outgrow pgvector, but pgvector is sufficient for MVP.

Authentication

• Email/password with Argon2id hashing
• OAuth (Google) with PKCE
• Refresh tokens stored as httpOnly secure cookies

Authorization

• Row-level checks in every handler: resource.user_id == auth.user_id
• Avoid multi-tenant footguns by scoping queries by user_id

Data protection

• TLS everywhere
• Encrypt sensitive fields at rest where applicable (e.g., OAuth tokens if stored)
• Minimize stored PII; store only what is required for features
• Provide deletion endpoints and hard-delete on request

Rate limiting + abuse

• IP-based rate limiting on auth endpoints
• User-based rate limiting on chat endpoints (token bucket)
• Bot protection on signup (hCaptcha/Turnstile)

LLM threat considerations

• Prompt injection: treat product descriptions and external content as untrusted
• Tool calling allowlist: only expose safe tools; validate tool args with Pydantic
• Data leakage: never include other users’ data in retrieval; enforce user_id filters
• Logging: redact tokens, emails, and message content in error logs by default

Pricing model

Freemium

• Free:
• limited chat messages/day
• 1 wishlist
• limited price alerts (e.g., 10)
• Pro ($9–$15/mo):
• higher chat limits
• unlimited wishlists
• more price alerts
• replenishment reminders
• advanced preference controls

Affiliate revenue (optional, later)

• Commission on purchases via affiliate links.
• Must be transparent: label affiliate links and allow opt-out.

Expansion pricing

• Family plan ($19–$29/mo): shared wishlists, gifting workflows
• Power user add-on: premium deal intelligence (sale calendars, bulk tracking)

Unit economics assumptions (rough)

• Primary cost driver: LLM usage.
• Control costs via:
• caching product search results
• summarizing conversation memory
• using smaller models for classification/sentiment
• limiting tool calls per message

Distribution strategy

• Start with a single wedge: price tracking + personalized recommendations in chat.
• Target communities where shopping optimization is common:
• deal forums
• productivity communities
• fashion subreddits

Channels

• SEO landing pages for “price drop alerts + AI recommendations” queries
• Short demo videos showing chat-to-wishlist-to-alert loop
• Partnerships with niche newsletters (deals, lifestyle)

Launch plan

1. Private beta (50–200 users)

• manual onboarding
• instrument everything

1. Public waitlist + invite codes
2. Product Hunt + Reddit AMAs (with strict transparency)

Growth loops

• Price alert notifications bring users back.
• Wishlist sharing (later) creates viral loop.
• “Weekly digest” of price drops + recommended buys.

Validate before full build

1) Concierge prototype (1–2 weeks)

• Use a simple web form + email:
• user submits what they want
• you manually return 3–5 recommendations + price tracking via existing tools
• Measure willingness to:
• share preferences
• save items
• act on alerts

2) Fake-door tests

• Landing page with:
• “Connect your Amazon history” (don’t implement; measure clicks)
• “Enable auto-replenish” (collect interest)

3) MVP testing approach

• Ship web chat + wishlist + price alerts.
• Run cohort tests:
• cohort A: generic recommendations
• cohort B: preference-based reranking + explanations

Metrics to track

• Activation: % who create wishlist item within first session
• Retention: D7/D30 returning users
• Alert conversion: % of alerts that lead to click-through
• Recommendation satisfaction: thumbs up/down per suggestion set
• Cost: LLM cost per active user per day

Phase 1 (MVP) — 6–10 weeks

• Web app chat
• User profile + preferences
• Product search integration (single source)
• Wishlist + price tracking + email notifications
• Basic replenishment reminders
• Privacy controls + deletion

Phase 2 — 8–12 weeks

• Multi-retailer ingestion
• Better ranking (learning-to-rank signals from clicks/saves)
• “Gift mode” workflow (recipient profile, constraints)
• Mobile-friendly PWA + push notifications

Phase 3 — 3–6 months

• Messaging channels (WhatsApp/Telegram; iMessage later)
• Deeper life-event planning (checklists + timelines)
• Partial in-chat checkout (start with affiliate deep links; later native)
• Family/shared profiles

Technical risks

• Product data quality/coverage: APIs may be limited or expensive.
• Price tracking reliability: retailer anti-bot measures; frequent changes.
• LLM cost and latency: must control tool calls and context size.

Market risks

• Users may not trust a “digital twin” without clear controls.
• Value may be unclear until multiple interactions occur (cold start).

Legal risks

• Scraping risks if not using approved APIs/feeds.
• Affiliate disclosure requirements.
• Data privacy compliance (GDPR/CCPA): deletion, export, consent.

Competitive risks

• Retailers can improve their own assistants.
• Browser extensions already own some price-tracking mindshare.

Mitigations

• Start with approved product feeds.
• Make privacy controls first-class.
• Focus on cross-retailer memory + explainability as differentiation.

Future features

• Account linking for purchase history (email receipt parsing, with consent)
• Mood detection (opt-in) using lightweight sentiment + user feedback
• Budget tracking with category caps and “safe to buy” signals
• Substitution engine for groceries (dietary + taste constraints)
• Calendar-aware planning (events, travel, seasonal needs)
• Shared household inventory + auto-replenish suggestions

Scalability direction

• Move from pgvector-only to hybrid retrieval:
• pgvector for personalization memory
• dedicated search engine (Meilisearch/Elastic) for product catalog
• Event-driven pipeline for product updates and price checks
• Online learning signals (click/save/purchase) feeding a reranker model

You are a senior full-stack engineer building the MVP of “ShopMind”, an AI shopping assistant.

GOAL
Build a production-ready MVP that supports: web chat assistant, user profile/preferences, product search (single source), wishlist, price tracking with scheduled checks, and email notifications.

TECH STACK (fixed)
- Frontend: Next.js (App Router) + TypeScript + Tailwind + shadcn/ui
- Backend: FastAPI (Python) + Pydantic
- DB: Postgres + pgvector
- Queue/Workers: Celery + Redis
- Email: Postmark (or SendGrid)
- LLM: OpenAI or Anthropic with tool calling
- Hosting: Vercel (web), Render/Fly (api/workers), Neon/Supabase (db)

DELIVERABLES
1) Monorepo with /apps/web and /apps/api
2) Database migrations (SQL) for all tables
3) Auth (JWT + refresh cookie), user profile CRUD
4) Chat endpoint with SSE streaming and tool calling
5) Product search integration (implement an adapter interface; provide one concrete adapter using a mock provider if real API keys not present)
6) Wishlist CRUD + price tracking scheduler
7) Email notifications for price drops and replenishment reminders
8) Basic admin/debug pages (view jobs, last price checks)
9) README with local dev + deployment steps

PROJECT STRUCTURE
/apps
  /web
    /app
      /(auth)
      /chat
      /wishlist
      /settings
    /components
    /lib (api client, auth helpers)
  /api
    /app
      main.py
      /routers (auth.py, me.py, chat.py, products.py, wishlist.py, replenishments.py)
      /services (llm.py, tools.py, product_sources/, ranking.py, embeddings.py, notifications.py)
      /workers (celery_app.py, tasks.py)
      /db (session.py, models.py)
      /migrations (SQL)

DATABASE SCHEMA
Implement the following tables exactly (UUID PKs): users, user_profiles, conversations, messages, products, product_prices, wishlists, wishlist_items, replenishments, product_embeddings, user_memory_embeddings.
Enable pgvector extension and create ivfflat indexes.

API ENDPOINTS
Auth:
- POST /v1/auth/register
- POST /v1/auth/login
- POST /v1/auth/refresh
- POST /v1/auth/logout

Profile:
- GET /v1/me
- PATCH /v1/me/profile

Chat:
- POST /v1/conversations
- GET /v1/conversations
- GET /v1/conversations/{id}
- POST /v1/conversations/{id}/messages  (SSE streaming)

Products:
- GET /v1/products/search?q=&category=&min_price=&max_price=
- GET /v1/products/{id}

Wishlist:
- POST /v1/wishlists
- GET /v1/wishlists
- POST /v1/wishlists/{id}/items
- PATCH /v1/wishlists/{id}/items/{item_id}
- DELETE /v1/wishlists/{id}/items/{item_id}

Replenishments:
- POST /v1/replenishments
- GET /v1/replenishments
- PATCH /v1/replenishments/{id}
- DELETE /v1/replenishments/{id}

LLM TOOL CALLING
Expose these tools to the model (validate args with Pydantic):
- search_products(query: str, filters: {category?, min_price?, max_price?, brand?}) -> list[product]
- get_user_profile() -> profile json
- add_to_wishlist(product_id: str, wishlist_id?: str, target_price_cents?: int)
- set_replenishment(product_id?: str, label?: str, cadence_days: int)

CHAT BEHAVIOR
- Use last 20 messages + a summarized long-term memory.
- Store sentiment label per user message using a cheap classifier model.
- The assistant must return: (a) natural language response, (b) up to 5 product cards with reasons, (c) explicit “why” explanation.

PRICE TRACKING WORKER
- Celery beat runs every 6 hours:
  - find wishlist_items where track_price=true
  - fetch latest price from product source adapter
  - insert into product_prices
  - if price <= target_price_cents (or dropped by X%), send email

NOTIFICATIONS
- Implement email templates: price_drop, replenishment_due, weekly_digest (optional)

LOCAL DEVELOPMENT
- Provide docker-compose for Postgres + Redis.
- Provide .env.example for API keys.
- Seed script to create demo products and a demo user.

DEPLOYMENT
- Web: Vercel with NEXT_PUBLIC_API_URL
- API/Workers: Render/Fly with Dockerfile
- DB: Neon/Supabase; run migrations on deploy

QUALITY BAR
- Type-safe API client in web app.
- Input validation everywhere.
- Clear error handling for missing product API keys (fallback to mock adapter).
- Minimal but complete UI flows: signup/login, chat, wishlist, settings.

Now implement the repo end-to-end.