[7.1] Product Configuration Page - FEUP-MEIC-DS-2025-26/madeinportugal.store GitHub Wiki

Product Configuration Page

NOTE: This is the documentation relative to the current Product Configuration Page implementation. If you are looking for the prototype documentation, please refer to this page.

Overview

The Product Configuration Page is a page available to sellers, designed to allow submission of product ideas to be listed on the marketplace, using a clean and intuitive interface, and assisted with an AI chatbot for helping fill each one of the required fields. Each submission is intended to be processed by the platform's inventory manager team for review and approval before being made available to customers. The inventory manager team has access to a dedicated Inventory Manager Dashboard, where they can view all product submissions, approve or reject them, and manage the listing of approved products on the marketplace through direct integration with the Jumpseller API.

The respective prototype is related to the issues #197 and #198. The current implementation tracks the issue #59.

Purpose

The purpose of the Product Configuration Page is to streamline the process of submitting product ideas for sellers, ensuring that all necessary information is collected efficiently and effectively. By leveraging AI assistance, the platform aims to reduce the friction associated with form filling and improve the overall user experience for sellers. The Product Edition Page also allows sellers to submit requests to edit their products on the platform. Additionally, the Inventory Manager Dashboard provides a centralized location for managing product submissions, facilitating better organization and decision-making for the inventory management team.

Key Features

User-Friendly Interface: A clean and intuitive layout that guides sellers through the product submission process.
AI Chatbot Assistance: An integrated AI chatbot that provides fast real-time assistance and suggestions for filling out the product configuration form.
Product Submission and Storage: The service stores all product submissions in a Firebase database, allowing for easy retrieval and management by the platform's inventory management team.
Product Edition: Sellers can also submit requests to edit their products on the platform.
Inventory Manager Dashboard: A dashboard, accessible to inventory managers, for reviewing, approving, or rejecting product creation/edition submissions.
Jumpseller API Integration: Direct integration with the Jumpseller API to facilitate the listing of approved products on the marketplace.

UI Description

Product Configuration Page

The page itself is very simple and intuitive. It presents a form for the seller to fill with the needed information, namely the product name, description, category, price, and image. An AI assistant is visible on the right side, capable of helping the user fill the forms with integrated suggestions. The assistant is able to offer suggestions with user prompts, but it's also able to provide real-time completions, as the user fills the form. It contains also a back-link to the vendor dashboard, since it is where this page is supposed to be accessed from. This page is accessible through this link.

Product Edition Page

This page is pretty similar to the previous one, but the forms in this page allows the user to edit existing products on the platform instead of creating new ones. It makes use of the same AI assistant for to also offer complete real-time suggestions.

Inventory Manager Dashboard

The Inventory Manager Dashboard is a dedicated interface for the platform's inventory management team. It provides a comprehensive overview of all product submissions, allowing managers to review, approve, or reject each submission. This page is accessible through this link.

Technologies

Web Application

The Product Configuration Page is built as a web application based on React and Next.js. React is a JavaScript library designed for building web user interfaces, infamous for its Virtual DOM and component-oriented development, which allow UI changes to be made dynamically without full page reloads. Next.js is a React framework made for building full-stack web applications, handling some of the most common challenges of developing web applications, such as routing, data fetching, and performance optimization right out of the box. Next.js was chosen for our application, not only for its effectiveness at building highly optimized applications, with advanced techniques such as pre-rendering, but also for improving developer experience with multiple developer-driven features and for integrating nicely with v0, which is an AI-powered UI generator we also used. Later, we will remove Next.js in favor of plain React with Module Federation, as to fully complete the final integration with the website platform.

This part of the service uses TypeScript as its main programming language, which improves upon JavaScript with static type checking and analysis. For styling components, we use TailwindCSS, a utility-first CSS framework that provides pre-designed, low-level, single-purpose styling HTML classes, avoiding the need to modify CSS files directly.

When a product is submitted to the platform, the server stores the product information in a Firebase Firestore database. Firebase Firestore is a NoSQL cloud database, known for providing real-time data synchronization and offline support, making it suitable for web and mobile applications. It is also praised for its scalability, security features, and seamless integration with other Google services, which can be beneficial for future expansions of the application. Firebase allows both the storage of product submission information as documents, but also the upload of product images to Firebase Storage, a cloud storage solution optimized for storing and serving user-generated content.

AI Integration

For the AI chatbot integration on the frontend side, we used the assistant-ui library, which provides pre-built components and functionalities for building AI-powered chat interfaces. The interfaces provided by this library are not only already very complete out of the box, but also can be highly customized to fit the needs of our application, in particular, the use of custom handlers, which is important for allowing the chatbot to fill the product configuration form fields when needed automatically.

Each one of the AI requests is proxied by our server, which is responsible for authenticating access, providing important context to the LLM used, etc. The AI service uses the Google Gemini API as its LLM, which provides access to state-of-the-art language models capable of understanding and generating human-like text. The Gemini models provide high performance in various natural language processing tasks and complex reasoning capabilities, making them suitable for our use case of assisting sellers in filling out product information.

Micro-service Communication

To communicate with the other micro-services of the platform, this service uses mainly Google Cloud Pub/Sub, a messaging service that allows asynchronous communication between different services through the use of topics and subscriptions. This was the agreed-upon method of communication between micro-services for the entire platform. In addition, this application is only a consumer of messages from other services, such as the Image Search Service (T7.2), and does not publish any messages itself.

Infrastructure and Deployment

As established by the project guidelines, we use the Google Cloud Platform (GCP) for hosting and deploying our application, namely, we deploy the application using Cloud Run, a serverless compute platform that automatically scales our application based on incoming traffic.

For containerizing our application, we use Docker, which not only is required to deploy our application on Cloud Run but also allows us to package the application and its dependencies into a single container image, ensuring consistency across different environments. The deployment process is simplified using Terraform configuration, based on the recommended Terraform template.

Since the application requires access to various sensitive information, such as API keys and database credentials, we use Google Secret Manager to securely store and manage these secrets. The secrets are accessed by the application at runtime, ensuring that sensitive information is not hardcoded into the application code or exposed in configuration files.

CI/CD Pipeline

To ensure smooth and efficient deployment of our application, we have implemented a Continuous Integration and Continuous Deployment (CI/CD) pipeline using GitHub Actions. A CI workflow verifies on every push to a branch that the application builds correctly, passes all the unit tests, and the code is properly formatted and respects the defined linting rules. This helps maintain code quality and catch issues early in the development process. At the time of writing, our statement test coverage is at 91.73%.

When a pull request is merged to the default branch, the application is automatically deployed using a CD workflow, which handles building the Docker image, pushing it to Google Container Registry, and updating the Cloud Run service.

Architecture

The Product Configuration Page and Inventory Manager Dashboard are united as a web application, and therefore follows a client-server architecture. Our team decided to deploy the entire application as a single unit/service. Since the backend is relatively simple, there was not a strong advantage in separating the frontend and backend into different services, which would add complexity to the deployment and maintenance of the application. This was also one of the reasons for choosing a full-stack framework such as Next.js. Nonetheless, we have plans on separating the two pages as different web applications in the future, to better follow the micro-service ideology and because the two services only share the same tech-stack and database, but have distinct functionalities and target users.

Nonetheless, the server itself communicates with other third-party services. Firstly, when a product is submitted, the server sends a request to Firebase Firestore and Firebase Storage to store the product information and image, respectively. Admins on the platform can then review the submitted products directly from the Inventory Manager Dashboard, which retrieves the submissions from Firebase. Secondly, the server also integrates with the Jumpseller API to facilitate the listing of approved products on the marketplace.

Thirdly, the server communicates with other micro-services of the madeinportugal.store platform through Google Cloud Pub/Sub.

Finally, the server's AI service uses Gemini AI models under the hood. The main responsibility of the AI service is to receive the seller's prompts and form information and generate a JSON file, parsable by the user interface to fill the product configuration form. The AI service is also divided into five sub-services:

Product JSON Agent - Transforms a user-provided product description into a structured JSON object.
Enhancement Form Agent - Completes partially filled product JSON objects, filling in values for missing fields.
Merger Agent - Merges two product JSON objects in an intelligent way
Validation Agent - Accesses the quality of the product JSON fields, applying suggestions if necessary.
Product Chat Agent - Generates user-facing questions to improve product descriptions.

Deployment Diagram

Our architecture follows the deployment diagram below:

C4 Diagrams

The C4 diagrams for our system can be found in the main Excalidraw Whiteboard.

Platform Integration

Although the whole path for services integration for the entire platform is not yet completely decided, we already moved on to the integration with other micro-services from other teams. The list of current integrations is as follows:

Landing Page (T1.2): The Inventory Manager Dashboard is accessible through the Landing Page, via the profile button.
Vendor Dashboard (T1.4): The Product Configuration Page is accessible from the Vendor Dashboard, allowing sellers to easily navigate to the product submission interface. It also contains a backlink to the Vendor Dashboard for improved navigation.
Image Search Service (T7.2): The Product Configuration Page integrates with the Image Search Service to provide real-time feedback on similar products already present in the marketplace based on the submitted image. This helps sellers avoid duplicate listings and encourages product diversity.

Project Management

Sprint 1

This sprint had the following three main goals:

Integrate Service with Rest of the Platform: Also defined as the main goal for all teams in this sprint, we aimed at ensuring the service is accessible from the rest of the platform and communicates properly with the other relevant micro-services.
Product Submission Review: Implement a basic dashboard for the inventory management team to review product submissions, instead of only relying on Google Sheets for that purpose.
Firebase Integration: Transition from Google Sheets to Firebase Firestore and Firebase Storage, for storing product submissions and images.

Sprint Overview

In this sprint, our team committed itself in finishing the following issues from our GitHub Project Board:

#295 - Creation of the Inventory Manager Dashboard UI
#296 - Transition to another storage solution beyond Google Sheets (which ended up being Firebase)
#297 - Integrate Jumpseller API for product registration
#294 - Integrate image search service (from team T7.2) on product configuration page, for seeing currently present similar products based on the submitted image.

After this sprint, we were successfully able to complete all the planned issues.

Sprint Retrospective

In this document, we will reflect on the team's performance during the sprint by highlighting what went well, what went wrong, and what is still a problem.

What Went Well

Great team collaboration and proactivity.
Effective resolution of issues and blockers throughout the sprint.
Collaboration with other teams for service integration.
Good adherence to the project's guidelines and best practices.
Consistent progress towards sprint goals and timely completion of tasks.

What Went Wrong

Communication between some team members was a bit lacking, leading to uncertainty about task progress.

What is Still a Problem

Some problems that ended unresolved with the delivery of the prototype (namely, resolution of some quirks of the AI integration) were still not completely addressed (mainly due to not being an objective for this sprint).

Sprint 2