HH-Lion Project Overview

What This Project Is

HH-Lion is the recommendation service behind Hungry Hub’s homepage.

Its job is to decide which restaurant sections to show when a user opens the app or website. The service supports both:

• guest users with little or no history
• logged-in users with enough behavior history for personalization

At a high level, HH-Lion tries to balance personalization, freshness, business control, and safety.

The Main Problem It Solves

Hungry Hub does not have one single type of user.

• Some users are brand new and have no history.
• Some users are returning guests with session signals only.
• Some users are logged-in members with enough past bookings and interactions.
• Some traffic needs editorial or business-driven placements.

Because of that, one recommendation strategy is not enough. HH-Lion is designed as a layered decision system rather than a single model endpoint.

What Happens When a Request Comes In

HH-Lion supports two homepage serving shapes:

• POST /v2/homepage: full homepage generation for model-driven serving flows.
• POST /v2/homepage/decide: conservative decision endpoint used by Tiger/Felidae when the homepage layout and restaurant hydration remain outside Lion.

The current Hungry Hub homepage integration uses the decision endpoint first: Tiger owns the homepage layout and hydrated restaurant payloads, while Lion ranks or selects item IDs for personalization-enabled sections.

When a request arrives, the system does this:

1. Identify the user context.
2. Decide whether the request is guest, session-driven, or truly personalized.
3. Retrieve candidates from one or more sources.
4. Merge those candidates.
5. Re-rank them when enough features are available.
6. Apply business rules, diversity constraints, and fallbacks.
7. Return homepage sections.

If deeper personalization is still being prepared, the API can return a fast baseline response first and complete the richer response through GET /v2/homepage/refresh.

Core Recommendation Logic

1. Identity First

The system always starts with identity resolution.

• anonymous_id keeps continuity for guest traffic.
• user_id enables member-level personalization.
• identity linking allows guest activity to be associated with a member later.

This matters because the recommendation strategy depends on what the system knows about the user.

2. Strategy Depends on Available Signal

HH-Lion does not force every request through the model.

It chooses from several strategies:

• personalized: for users with enough history
• cohort_popularity: for cold-start and anonymous users
• search_intent: when current session/search behavior gives strong signals
• fallback_global: when normal retrieval or ranking cannot be trusted

This is a practical design choice. A model is strongest when there is enough signal; otherwise simple cohort or popularity logic is more reliable.

3. Multiple Candidate Sources

Homepage items can come from different sources, including:

• model retrieval through embeddings and FAISS
• session-based retrieval
• cohort popularity retrieval
• new item retrieval

Instead of trusting one source, HH-Lion combines them. This reduces over-reliance on any single signal and improves robustness.

4. Candidate Merge

After retrieval, candidate lists are merged using Reciprocal Rank Fusion (RRF).

Why this matters:

• it lets multiple retrieval sources contribute
• it keeps the system stable even if one source is weaker
• it is easier to reason about than a fully opaque merge step

5. Re-ranking

After merging, the system can re-rank items with CatBoost when the feature contract is healthy enough.

This second stage is where the system can use richer signals such as:

• user behavior features
• item popularity and conversion features
• contextual signals
• categorical matching and relevance signals

If the ranker is unavailable or feature completeness is too low, the system can fall back safely instead of returning untrusted results.

6. Business and Quality Constraints

The final list is not just “highest score wins”.

The system also applies:

• deduplication
• diversity rules
• safe global fallback

This is important because a production recommendation system must optimize for product quality and operational safety, not just model score.

Training Logic

The training pipeline uses real interaction data from ClickHouse.

Current logic:

• training data comes from booking_confirmed restaurant events
• only valid rows are used
• data is split temporally, so validation happens on later events
• model artifacts are logged to MLflow
• the selected registered model alias is served via MLFLOW_MODEL_NAME + MLFLOW_MODEL_ALIAS

This design avoids train/serve skew and makes model promotion traceable.

In simple terms:

1. users generate events
2. events land in Kafka
3. Kafka consumer writes them to ClickHouse
4. feature jobs compute online/offline features
5. training reads those features/events
6. model is evaluated and registered
7. serving loads a specific MLflow run

Why the Architecture Looks Like This

The system has two loops.

Online Loop

• serve homepage requests
• emit impression events
• collect fresh behavior

Offline Loop

• ingest behavior into ClickHouse
• compute features
• train and evaluate models
• publish a new model version

This split exists because recommendations need both:

• low-latency serving right now
• slower learning and model improvement over time

Why This Design Is Good for the Business

This project is useful because it is not only a model demo. It is an operational recommendation platform.

It gives Hungry Hub:

• personalized homepage content for members
• reasonable recommendations for guests and cold-start traffic
• explainable fallback behavior
• measurable model lifecycle through MLflow
• safer deployment through staged promotion and rollback

Risks the Project Intentionally Handles

The implementation already assumes real-world failure modes:

• model may be missing
• Redis may be unavailable
• queue workers may lag
• feature completeness may drop
• personalization may take too long

Instead of failing hard in all of those cases, HH-Lion is designed to degrade gracefully and still return a usable homepage.

Short Summary for a Team Lead

HH-Lion is a production-focused homepage recommendation service, not just a ranking model.

Its core logic is:

• use the best available user signal
• retrieve candidates from multiple sources
• merge and re-rank them
• enforce business and quality constraints
• fall back safely when confidence or infrastructure is weak

The reason this project is valuable is that it connects the full loop:

• data collection
• feature computation
• model training
• model serving
• production safeguards

That makes it a practical foundation for personalization at Hungry Hub.