How aemorabr/ecommerce-recommendation-system works
This is a full-stack e-commerce recommendation product. The main user flow is browsing the catalog in the frontend, requesting recommendations through the Node.js API, and receiving strategy-selected results from the FastAPI ML service; the Node API also enriches recommendations with product records. The ML service supports collaborative, content-based, hybrid, and popularity strategies, similar-item/customer queries, and model retraining and metrics. Some UI and ML wiring is documented rather than visible in excerpts, so those links cite the README; unsampled implementation details are not inferred.
Main entry points: main.py ML API · server.js Express server · database.py ML DB access · products.js Product routes
Components 18
Storefront
- Catalog UI
frontend/src/pages/index.tsx - Catalog widgets
frontend/src/components - Frontend API client
frontend/src/services/api.ts
Backend API
- Express server
backend-nodejs/server.js - Product routes
backend-nodejs/routes/products.js - Customer routes
backend-nodejs/routes/customers.js - Recommendation routes
backend-nodejs/routes/recommendations.js - Node DB access
backend-nodejs/services/database.js
Recommendation ML
- ML API
ml-service/app/main.py - API schemas
ml-service/app/models/schemas.py - Collaborative filtering
ml-service/app/services/recommendation_engine.py - Content recommender
ml-service/app/services/content_based_recommender.py - Hybrid recommender
ml-service/app/services/hybrid_recommender.py - Customer embeddings
ml-service/app/services/customer_embedding_generator.py - Recommendation cache
ml-service/app/services/cache.py - ML DB access
ml-service/app/services/database.py
Data
- PostgreSQL + pgvector
database/schema.sql
Other components
- Shopper
Connections 23
- Shopper → Catalog UI: browses
README.md - Catalog UI → Frontend API client: requests data
- Frontend API client → Express server: calls API
- Express server → Product routes: routes requests
backend-nodejs/server.js - Express server → Customer routes: routes requests
backend-nodejs/server.js - Express server → Recommendation routes: routes requests
backend-nodejs/server.js - Product routes → Node DB access: queries products
backend-nodejs/routes/products.js - Customer routes → Node DB access: queries history
backend-nodejs/routes/customers.js - Product routes → ML API: requests recommendations
backend-nodejs/routes/products.js - Recommendation routes → ML API: proxies requests
backend-nodejs/routes/recommendations.js - ML API → API schemas: validates responses
ml-service/app/main.py - ML API → Collaborative filtering: dispatches strategy
ml-service/app/main.py - ML API → Content recommender: dispatches strategy
ml-service/app/main.py - ML API → Hybrid recommender: dispatches strategy
ml-service/app/main.py - ML API → Customer embeddings: retraining uses
ml-service/app/main.py - ML API → Recommendation cache: invalidates entries
ml-service/app/main.py - Collaborative filtering → ML DB access: reads and writes
ml-service/app/services/recommendation_engine.py - Content recommender → ML DB access: reads and writes
ml-service/app/services/content_based_recommender.py - Customer embeddings → ML DB access: reads and writes
ml-service/app/services/customer_embedding_generator.py - Hybrid recommender → Collaborative filtering: combines strategies
- Hybrid recommender → Content recommender: combines strategies
- ML DB access → PostgreSQL + pgvector: queries embeddings
- Node DB access → PostgreSQL + pgvector: queries catalog