Skip to main content

Recommendation Service 🤖

The Recommendation Service is responsible for generating personalized product recommendations for users in ShopVerse based on their interaction history.

It is a purely event-driven, read-optimized service that improves user engagement without affecting core transactional workflows.

🎯 Responsibilities​

The Recommendation Service handles:

  • Consuming user interaction events from Kafka
  • Storing interaction history
  • Computing recommendation scores
  • Generating personalized product recommendations
  • Exposing recommendation APIs to clients

🧠 Why a Separate Recommendation Service?​

Recommendations are:

  • Data-driven
  • Continuously evolving
  • Computationally intensive

Separating them ensures:

  • No impact on order or payment flows
  • Independent experimentation with algorithms
  • Easy evolution from rule-based → ML-based models
  • Independent scaling

🏗️ High-Level Architecture​

📡 Event Consumption Model​

The Recommendation Service does not receive direct API calls from other services. It reacts only to Kafka events.

Events Consumed:​

  • VIEW_PRODUCT
  • ADD_TO_CART
  • ORDER_PLACED

🔁 Interaction Processing Flow​

🗄️ Data Model​

UserInteraction Document​

  • id
  • userEmail
  • productId
  • eventType (VIEW, CART, ORDER)
  • timestamp

Recommendation Document​

  • id
  • userEmail
  • productId
  • score
  • source (PERSONAL / POPULAR)
  • createdAt

MongoDB is used for:

  • Flexible schema
  • High write throughput
  • Fast aggregation queries

🧮 Recommendation Scoring Strategy​

ShopVerse uses a weighted interaction-based scoring model.

InteractionWeight
VIEW_PRODUCT+1
ADD_TO_CART+3
ORDER_PLACED+5

Scoring Logic:​

  • Scores accumulate per user-product pair
  • Recent interactions weigh more
  • Products with highest scores are recommended

This approach is:

  • Simple
  • Explainable
  • Easily extendable to ML models

🧠 Recommendation Types​

1️⃣ Personalized Recommendations​

  • Based on user’s own interactions
  • Returned when sufficient data exists
  • Based on global interaction frequency
  • Used for new or inactive users

🌐 APIs​

Recommendation API​

MethodEndpointRoleDescription
GET/api/recommendationsCUSTOMERGet recommended products

Example Response:

[
  {
    "productId": "PROD123",
    "score": 12.5,
    "source": "PERSONAL"
  }
]

🔐 Security Model​

  • Accessed via API Gateway

  • Identity propagated using:

    • X-User-Email
    • X-User-Role

  • Only authenticated customers can fetch recommendations

  • Admin access is restricted

🛡️ Reliability & Idempotency​

  • Kafka events may be delivered multiple times
  • Each interaction is uniquely identified
  • Duplicate interactions are safely ignored
  • Consumers commit offsets only after successful processing

⚠️ Failure Scenarios​

❌ Kafka Lag​

  • Recommendations delayed
  • Core services unaffected

❌ MongoDB Down​

  • Interactions retried
  • No data loss due to Kafka retention

❌ No Interaction Data​

  • Fallback to popular recommendations

⚙️ Key Components​

  • UserInteractionConsumer – Kafka consumer
  • RecommendationService – Scoring & aggregation logic
  • UserInteractionRepository – MongoDB persistence
  • RecommendationRepository – Recommendation storage
  • RecommendationController – REST API
  • GatewayHeaderAuthenticationFilter – Security
  • GlobalExceptionHandler – Error handling

📈 Scalability Considerations​

  • Stateless service
  • Kafka partitions enable parallel consumption
  • MongoDB supports horizontal scaling
  • Recommendation APIs are read-optimized

🧪 Testing Strategy​

  • Unit tests for scoring logic
  • Kafka consumer tests
  • MongoDB aggregation tests
  • Security tests for role enforcement

🚀 Future Enhancements​

  • Collaborative filtering
  • ML-based recommendations
  • Time-decay scoring
  • Category-based suggestions
  • A/B testing of algorithms

The current design supports easy evolution without architectural changes.

📌 Summary​

The Recommendation Service provides:

  • Personalized user experience
  • Event-driven scalability
  • Clean separation from core workflows
  • Extendable recommendation logic

It transforms user behavior into intelligent product discovery, completing the ShopVerse ecosystem.