Recommendations Prototype

Vision

The long-term vision for the Recommendations Prototype is to evolve into a fully integrated and intelligent personalization layer that enhances the shopping experience across the madeinportugal.store platform. Our aim is to transform recommendations into a core capability that drives engagement, significantly enhances product discoverability, and improves user satisfaction. The system will be built on a scalable, cloud-native architecture to support future growth and model complexity.

Overview

The Recommendations Prototype demonstrates a minimal yet functional pipeline for product recommendations in the madeinportugal store. It includes a seeded Postgres schema (buyers, sellers, products, orders, reviews, likes and follows), a lightweight REST backend, a simple React demo UI and an ML service powered by the Surprise library.

The prototype is related to issue #321.

Purpose

The purpose of the prototype is to streamline experimentation with recommendation strategies over a realistic domain schema, provide clear REST endpoints the frontend can consume, and establish a path for personalized recommendations.

Key Features

• User-Friendly Interface: Simple and clean Demo UI to validate backend connectivity and visualize responses.
• Recommendation Endpoint (Prototype): Backend exposes a simple mock /api/recommendations/:userId for quick integration.
• ML Service with Surprise (SVD): Separate FastAPI service that trains a collaborative filtering model on simulated data and serves top‑N product IDs per user.

Prototype UI Description

The demo UI focuses on simplicity and validation:

• Shows backend connection status and health payload.
• Can be extended to display products and recommendations for a given user.

Prototype Mockup

The following mockup illustrates the intended user experience for the demo UI and the end‑to‑end flow behind recommendations:

Technologies

Web Application

• Frontend: ReactJS + Vite (simple stateful components and fetch calls).
• Backend: Node.js + Express + TypeScript + TypeORM (REST endpoints, Postgres access).
• Database: PostgreSQL (via Docker locally; Cloud SQL in GCP for production).

ML Integration

This prototype uses the Surprise library (Python) with an SVD collaborative filtering algorithm, served through a FastAPI service that exposes GET /recommendations/{user_id} and returns a list of product IDs. The design is intended to evolve toward scheduled training jobs and Redis (Memorystore) caching so recommendations can be served with low latency.

Infrastructure and Deployment

Both the backend and ML services run on Google Cloud Run. The backend connects to Cloud SQL (Postgres) over a private VPC Connector, and secrets such as database and Redis credentials are managed in Secret Manager. Memorystore (Redis) is provisioned to cache recommendation lists. All of these resources and their configuration are defined and provisioned with Terraform.

Architecture

The data flow begins with the React client, which calls the backend API (Recommendation API) running on Cloud Run. For recommendations, the API first checks the Redis cache (Memorystore). If a pre-computed list exists, it is fetched and enriched with product data from the database (Cloud SQL, accessed via a VPC Connector). The recommendations in Redis are generated and periodically updated by a separate ML service (Surprise), also on Cloud Run, ensuring the backend remains focused on request handling and data serving.

Jumpseller is used because it is the standard platform adopted across the system, allowing easy access to the product data required for generating recommendations. The data obtained from Jumpseller is then processed to prepare it for model training. This preprocessing step removes unnecessary columns and formats the information in a way that supports efficient and accurate recommendation generation. The Best Selling Products API is used when a user has no available recommendations, which occurs only in cases where the user is new and has not yet interacted with the platform.

Surprise is a Python library designed to generate product recommendations based on user interactions. Because it includes a wide range of built-in models and algorithms, it offers a more efficient solution than developing new recommendation components from scratch. This approach reduces development effort and allows attention to be directed toward other aspects of the project.

Redis functions as an in-memory cache that is periodically refreshed (e.g., daily at 2 p.m.). This helps minimize load on the cloud infrastructure by avoiding unnecessary recomputation. Caching is especially valuable when handling negative reviews, which can influence existing recommendation results and may require frequent updates. Since the project is not expected to serve millions of users, an in-memory cache offers an efficient and lightweight alternative to a full database, while also providing faster data retrieval.

Architecture Diagram

Our architecture follows the diagram below:

Future Work

• Integrate ML outputs in backend responses (Redis lookup + metadata join) instead of mock results.
• Replace simulated ML training data with weighted interaction signals (wishlist, review ratings, orders, follows).
• Add cold‑start strategies (popular/trending, category‑based, seller‑based).
• Extend UI to the landing page with a Recommendation Section.
• Add monitoring (cache hit rate, latency, model freshness) and scheduled re‑training.