[4.2 Prototype] Map Integration for Searches - FEUP-MEIC-DS-2025-26/madeinportugal.store GitHub Wiki

Prototype Team 4.2

Repository

Goals

This prototype implements initial approaches to the identified issues.

The issues integrate smoothly without much overhead in implementation, as most of them — except for #26 — rely on the product concept. While not perfect in visual terms, we believe this is a functional prototype that effectively expresses and meets the issue requirements definied by the Product Owners.

Members

Contents

Backend API Reference

This document describes the REST API endpoints provided by the backend Flask service.

Endpoints

GET /api/products

  • Description: Returns a list of all products.
  • Response:
    • 200 OK: Array of product objects.

GET /api/product/<id>

  • Description: Returns details for a single product by ID.
  • Parameters:
    • id (string): Product identifier.
  • Response:
    • 200 OK: Product object.
    • 404 Not Found: If product does not exist.

POST /api/search

  • Description: Search for products by location, category, or other criteria.
  • Body: JSON with search parameters (e.g., location, bounds, category).
  • Response:
    • 200 OK: Array of matching product objects.

Error Handling

  • 400 Bad Request: Invalid input.
  • 404 Not Found: Resource not found.
  • 500 Internal Server Error: Unexpected error.

Example Product Object

{
  "id": "abc123",
  "name": "Portuguese Organic Olive Oil",
  "description": "Premium extra virgin olive oil produced using traditional organic methods in Portugal.",
  "price": 12.99,
  "image_url": "https://...",
  "location": { "lat": 41.15, "lng": -8.61 },
  "category": "Food"
}

Translation Service

Integration

  • The frontend calls the LibreTranslate API at http://localhost:5000/translate.
  • Only supported languages are shown in selectors and used in API calls.
  • Language codes are mapped between i18n and LibreTranslate.

Supported Languages

  • English (en)
  • French (fr)
  • German (de)
  • Dutch (nl)
  • Albanian (sq)
  • Arabic (ar)
  • Azerbaijani (az)
  • Basque (eu)
  • Bengali (bn)
  • Bulgarian (bg)
  • Catalan (ca)
  • Chinese (zh)
  • Danish (da)
  • Czech (cs)
  • Finnish (fi)
  • Galician (gl)
  • Estonian (et)
  • Esperanto (eo)

Example API Call

POST /translate
{
  "q": "Hello world",
  "source": "en",
  "target": "fr"
}

Adding More Languages

  • Update the langMap and translations objects in the frontend code.
  • Ensure LibreTranslate supports the new language.

See frontend/index.html and frontend/products.html for integration details.

System Architecture

This document provides a detailed overview of the architecture for Prototype_42, including component and deployment diagrams, and a breakdown of each subsystem.

Component Diagram

Component Diagram

Deployment Diagram

Deployment Diagram

Component Breakdown

Frontend

  • index.html: Map-based product search, language selector, dynamic translation.
  • products.html: Product listing, language selector, dynamic translation, navigation to product details.
  • product-detail.html: Product story, timeline, language selector, dynamic translation.
  • script.js: Shared JS logic.
  • style.css: Shared styles.
  • translate.js: Translation logic for UI (hardcoded) and content(dynamic).

Backend

  • main.py: Flask API for product data, search, and business logic.
  • seed_data.py: Script to seed the database with initial product data.
  • requirements.txt: Python dependencies.

Translation Service

  • LibreTranslate: Open-source translation API, containerized for local/cloud use.
  • docker-compose.yml: Orchestrates LibreTranslate and other services locally.

Infrastructure

  • main.tf, variables.tf, terraform.tfvars: Terraform scripts for provisioning cloud resources (e.g., Google Cloud Run, storage, networking).

Frontend

This section explains the user flow and features of the Prototype_42 frontend.

Pages

index.html (Map Search)

  • Search for products by location using an interactive map (Leaflet.js).
  • Enter a location, select a category, and view results as map markers and a list.
  • Language selector for multilingual UI.

products.html (Product List)

  • Displays all products in a grid.
  • Click a product card to view its story.
  • Language selector for multilingual UI.

product-detail.html (Product Story)

  • Shows detailed product information and a timeline/story.
  • Timeline events are translated.
  • Back link to product list.

Language & Translation

  • Language selector is available on all pages.
  • UI and product content are translated using LibreTranslate.
  • Only supported languages are shown.

Navigation

  • Clicking a product always navigates to its detail page.
  • Back links and navigation are consistent across languages.

For UI details, see the HTML files in the frontend/ folder.