AI Suggested Smart Bundles

Overview

This prototype aims to enhance the marketplace experience by integrating an AI-powered bundling system directly into the product page. The system analyzes the product catalog and automatically suggests complementary items based on relevant product characteristics and relationships.

The goal is to help users quickly find relevant product combinations that suit their needs without spending excessive time searching for the best options.

Objectives

• Develop an intelligent system capable of generating relevant product bundles.
• Design a clear and responsive interface to present the suggested bundles.
• Ensure that recommendations are coherent, diverse, and aligned with product context.
• Provide concise explanations for each suggestion to improve transparency and trust.

Development Tools

Package Managers

• npm - used to install and manage all frontend and microfrontend dependencies (React, Material UI, Webpack, Babel).
• pip - used to install backend dependencies through requirements.txt (Flask, google-genai, dotenv, gunicorn).

Reproducible Development Environment

• Docker - used to containerize the microfrontend for deployment on Google Cloud Run.
• Google Cloud Run - provides a consistent execution environment for both the backend and the microfrontend, ensuring identical behavior across machines.
• Environment Variables (.env) - the GEMINI_KEY is loaded through dotenv, allowing the backend to run consistently on any system with the same configuration.

System Flow

High Level

• The product page loads the BundleSection microfrontend.
• The microfrontend requests suggestions from /api/suggestions.
• The backend retrieves product data, splits the catalog, and sends parallel requests to Gemini.
• Gemini returns partial suggestions, which the backend aggregates into a final bundle.
• The backend returns up to 3 recommended products as JSON.
• The microfrontend renders the items using Material UI.

Summarized flow

Product Page -> Microfrontend -> Backend API -> Gemini (multi workers) -> Backend Aggregation -> Microfrontend UI -> User

Development Guide

Backend Setup

Prerequisites:

• Python 3.9+
• A valid Gemini API key

Environment Setup Inside the backend/ directory, create a .env file: GEMINI_KEY=your_gemini_key_here

Install Dependencies From the backend folder: pip install -r requirements.txt

Run the Backend Locally To test the backend API locally: python server_local.py The service will run at: http://127.0.0.1:5000 This exposes the endpoint: /api/suggestions Note: When running locally, make sure your frontend calls localhost:5000.

Backend – Console Demo (Optional)

You can test the bundling logic directly via terminal:python start.py This runs the suggestion bot using the sample product_list included in the file.

Microfrontend Setup (bundle-microfrontend)

Install Dependencies From src/bundle-microfrontend/: npm install Run Locally npm start This launches the microfrontend at: http://localhost:3001

It exposes remoteEntry.js via Webpack Module Federation, allowing other apps to dynamically import the BundleSectioncomponent.

Microfrontend – Production Build

To generate the optimized build: npm run build This produces the dist/ folder containing:

• remoteEntry.js
• index.html
• static assets

Deployment (Cloud Run)

Microfrontend Deployment Build and upload the Docker image: gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/bundle-microfrontend Deploy to Cloud Run:

gcloud run deploy bundle-microfrontend \
  --image gcr.io/YOUR_PROJECT_ID/bundle-microfrontend \
  --region europe-west1 \
  --allow-unauthenticated

Once deployed, Cloud Run will give you a public URL, like: https://bundle-microfrontend-xyz.a.run.app/remoteEntry.js

Backend Deployment

cd backend/
gcloud run deploy ai-suggestion-backend \
  --source . \
  --region europe-west1 \
  --allow-unauthenticated \
  --set-env-vars GEMINI_KEY=YOUR_GEMINI_API_KEY

Frontend (Static Hosting)

To update the deployed static frontend: gsutil -m cp -r src/frontend/* gs://dsprototype-frontend/

Repository

https://github.com/FEUP-MEIC-DS-2025-26/AI_suggestion_bundle

Screenshot

Sprint 1 Retrospective

What went well

What could be improved

Verifiable Action Points