SmartRec

AI-powered product recommendation platform — hybrid ranking, grounded shopping assistant, and white-label storefront ready for any catalog.

Built by Saransh Garg · Portfolio / resume project

---

Highlights

• Hybrid recommender — content-based (TF-IDF), item–item collaborative filtering, popularity, recency, and cold-start handling
• Grounded AI assistant — retrieves only real catalog products (optional OpenAI; rule-based fallback)
• Full commerce loop — browse, wishlist, cart, addresses, orders, reviews, event tracking, rec→purchase attribution
• White-label ready — brand name, theme, currency, and catalog via config/ (no code rewrite)
• Production-shaped — FastAPI + React, Alembic, Redis-ready cache, Docker Compose, GitHub Actions CI

---

Tech stack

Layer	Technologies
Backend	FastAPI, SQLAlchemy, Pydantic, Alembic, pytest
Recommenders	TF-IDF / cosine, collaborative filtering, hybrid weighted ranker
Frontend	React, TypeScript, Vite
Data	SQLite (local) · Postgres + Redis (Docker / prod)
Auth	JWT, password reset, email verify hook, Google OAuth stub
Payments	Demo checkout + Stripe-ready integration
Ops	Docker Compose, Nginx, GitHub Actions

---

Quick start

Backend

cd backend
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
python scripts\seed.py
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Frontend

cd frontend
npm install
copy .env.example .env
npm run dev

App	http://127.0.0.1:5173
API docs	http://127.0.0.1:8000/docs
Demo admin	demo@smartrec.com / Password123!

---

Architecture

React storefront
      │ REST
      ▼
FastAPI routers → services → recommendation engine → DB
                              ├── Popularity
                              ├── Content-based (TF-IDF)
                              ├── Collaborative (item–item)
                              └── Hybrid + cold-start
AI assistant → intent → catalog search → rank → explain
Cache: in-memory (dev) or Redis (prod)

Hybrid score

finalScore =
  contentScore       × REC_CONTENT_WEIGHT
+ collaborativeScore × REC_COLLAB_WEIGHT
+ popularityScore    × REC_POPULARITY_WEIGHT
+ recencyScore       × REC_RECENCY_WEIGHT

Weights are configurable via environment variables.

---

Features

• Product browse, keyword + semantic search, filters, PDP, ratings/reviews
• Personalized “for you”, similar items, because-you-viewed, trending, popular
• Wishlist, likes, cart, shipping addresses, order lifecycle
• Event tracking (views, clicks, cart, purchase, rec impressions)
• Admin: product CRUD, low-stock inventory, order status
• Analytics dashboard + A/B experiment groups
• White-label branding API: GET /api/config/branding

Evaluation notes: docs/EVALUATION.md
White-label guide: WHITE_LABEL.md

---

White-label (for any business)

1. Edit config/branding.json — name, colors, currency, categories, demo users
2. Replace config/catalog.json — your products
3. Re-seed: python backend/scripts/seed.py
4. Restart API + frontend

---

Docker

docker compose up --build

Runs Postgres, Redis, API (multi-worker), and Nginx frontend.

SECRET_KEY=your-long-secret
OPENAI_API_KEY=sk-...   # optional

---

Project structure

├── backend/           FastAPI, recommenders, seed, tests
├── frontend/          React + Vite storefront
├── config/            branding.json + catalog.json (white-label)
├── docs/              Evaluation methodology
├── .github/workflows  CI (pytest + frontend build)
├── docker-compose.yml
└── WHITE_LABEL.md

---

Tests

cd backend
.\.venv\Scripts\Activate.ps1
pytest
python scripts\evaluate_recommendations.py

Frontend:

cd frontend
npm run build

---

Environment

See backend/.env.example and frontend/.env.example.
Never commit real API keys or .env files.

---

License

MIT © Saransh Garg