Marketplace Search and Recommendation Service

This repository contains a Kotlin + Spring Boot starter backend for marketplace search and recommendations. It is intentionally designed as a clean first slice that your marketplace team can extend into production search pipelines, offline ranking, and personalized recommendations.

What is included

• Search API with:
  • free-text token matching
  • light typo tolerance
  • filtering by category, price, stock, and tags
  • ranking boosted by title match, ratings, reviews, popularity, and inventory
• Recommendation API with:
  • user affinity signals from preferred categories and tags
  • context-item similarity for "similar products" style recommendations
  • popularity and price-fit blending
• Seed marketplace catalog and demo user profiles for fast iteration
• Spring Boot test coverage for the main relevance flows

Project structure

• src/main/kotlin/com/marketplace/search/api: REST endpoints
• src/main/kotlin/com/marketplace/search/catalog: domain models and in-memory seed repository
• src/main/kotlin/com/marketplace/search/search: search ranking logic
• src/main/kotlin/com/marketplace/search/recommendation: recommendation logic

API endpoints

List catalog

GET /api/items

Search catalog

GET /api/search?query=wireless+headphones&category=electronics&limit=5

Additional query parameters:

• minPrice
• maxPrice
• tags
• inStockOnly

Recommend for a user

GET /api/users/user-1/recommendations?contextItemId=itm-1004&limit=6

Use contextItemId for "related items" ranking around a product detail page.

Run locally

1. Ensure Java 17 is installed.
2. Generate or add a Gradle wrapper if your environment does not already provide one.
3. Run ./gradlew bootRun

Recommended next steps

• Replace the in-memory repository with PostgreSQL or Elasticsearch/OpenSearch indexing pipelines.
• Add event ingestion for clicks, views, carts, and purchases.
• Learn search ranking weights from interaction data instead of hardcoding them.
• Add collaborative filtering or vector similarity for richer personalization.
• Introduce seller quality, margin, and fulfillment signals into ranking.