HH-Lion Project Onboarding

hh-lion is Hungry Hub’s recommendation service for homepage personalization.

When a user opens the homepage, hh-lion helps decide which restaurant sections or restaurant items are shown, and in what order. It supports guest users, logged-in users, business-controlled placements, and safe fallback behavior.

1. What HH-Lion Does

HH-Lion handles four main responsibilities:

1. Serve homepage recommendation decisions.
2. Collect recommendation and interaction signals.
3. Prepare data for training and evaluation.
4. Manage the model lifecycle from training to serving.

At a high level:

• hh-pegasus renders the customer-facing homepage.
• hh-felidae / Tiger owns homepage structure, section configuration, and hydrated restaurant payloads.
• hh-lion ranks or selects restaurant item IDs for recommendation-enabled sections.

2. Main Homepage Flow

flowchart LR
    User["User opens homepage"]
    Pegasus["hh-pegasus<br/>frontend"]
    Tiger["hh-felidae / Tiger<br/>homepage API"]
    Lion["hh-lion<br/>recommendation service"]
    Response["Ranked restaurant IDs<br/>and metadata"]
    Page["Homepage rendered"]

    User --> Pegasus
    Pegasus --> Tiger
    Tiger --> Lion
    Lion --> Response
    Response --> Tiger
    Tiger --> Pegasus
    Pegasus --> Page

HH-Lion supports two homepage serving shapes:

• a fuller model-driven flow where Lion can produce homepage recommendation output
• a decision-layer flow where Tiger keeps ownership of homepage layout and restaurant hydration, while Lion ranks or selects items for eligible sections

The current integration shape described in the project docs uses the decision-layer flow first. Tiger owns the homepage layout and hydrated restaurant data. Lion returns recommendation decisions for eligible sections.

3. Request Decision Flow

When HH-Lion receives a homepage request, it follows this flow:

flowchart TD
    A["Homepage recommendation request"]
    B["Resolve identity<br/>anonymous_id, session_id, user_id"]
    C["Read request context<br/>geo, language, device, referrer"]
    D["Choose recommendation strategy"]
    E["Retrieve candidate restaurants"]
    F["Merge candidate lists"]
    G["Re-rank when features are available"]
    H["Apply business rules, diversity, deduplication, fallback"]
    I["Return ranked sections or item IDs"]
    J["Emit impression telemetry"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J

The important idea is that HH-Lion is not just one model endpoint. It is a layered decision system:

1. Identify the user and request context.
2. Decide which strategy is appropriate.
3. Retrieve candidates from one or more sources.
4. Merge candidates.
5. Re-rank if the feature contract is healthy.
6. Apply product and safety rules.
7. Return a usable homepage response.

4. Recommendation Strategies

The project docs define the personalization threshold as:

• at least 3 bookings, or
• at least 10 interactions in the last 180 days.

If a user does not have enough signal, HH-Lion can use cohort, session, search, or global fallback behavior.

5. Candidate Retrieval and Ranking

flowchart TD
    A["Request context"]
    B["Model retrieval<br/>Two-Tower + FAISS"]
    C["Session retrieval"]
    D["Cohort popularity retrieval"]
    E["Search intent retrieval"]
    F["New item retrieval"]
    G["Candidate merge<br/>RRF"]
    H["Re-ranking<br/>CatBoost when available"]
    I["Final ranked restaurants"]

    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    B --> G
    C --> G
    D --> G
    E --> G
    F --> G
    G --> H
    H --> I

HH-Lion can retrieve candidates from multiple sources:

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

The retrieved candidates are merged using Reciprocal Rank Fusion. After merging, CatBoost re-ranking can be used when enough features are available. The final result also applies deduplication, diversity rules, and fallback handling.

6. Tracking and Event Flow

User behavior is collected as canonical interaction events.

sequenceDiagram
    participant User
    participant Pegasus as hh-pegasus
    participant Tiger as Tiger / hh-felidae
    participant Kafka
    participant Lion as hh-lion ingestion
    participant ClickHouse

    User->>Pegasus: View, click, search, checkout, book
    Pegasus->>Tiger: Send tracking event
    Tiger->>Kafka: Publish canonical event
    Kafka->>Lion: Consume event
    Lion->>Lion: Validate event quality
    Lion->>ClickHouse: Store valid event

The primary ingestion topic is:

hh.lion.interaction.events

With environment namespacing, the effective topic is:

<NAMESPACE>.hh.lion.interaction.events

Canonical event types:

Invalid events go to the internal dead-letter topic:

hh.lion.interaction.events.dlq

7. Data Flow

flowchart LR
    Events["Interaction events"]
    Kafka["Kafka"]
    Validation["Event validation"]
    DLQ["DLQ"]
    ClickHouse["ClickHouse"]
    FeatureJobs["Feature jobs"]
    Redis["Redis / online serving state"]
    TrainingData["Training and evaluation data"]

    Events --> Kafka
    Kafka --> Validation
    Validation -->|valid| ClickHouse
    Validation -->|invalid| DLQ
    ClickHouse --> FeatureJobs
    FeatureJobs --> Redis
    ClickHouse --> TrainingData
    FeatureJobs --> TrainingData

ClickHouse is the main offline store for interaction history and training data. Redis is used for online serving state, session support, and cache-like serving needs.

8. Training Flow

The training pipeline uses real interaction data from ClickHouse.

Current training logic described in the project docs:

• training data comes from booking_confirmed restaurant events
• only valid rows are used
• validation uses a temporal split
• model artifacts are logged to MLflow
• serving loads a registered model through MLFLOW_MODEL_NAME and MLFLOW_MODEL_ALIAS

flowchart TD
    A["Validated events in ClickHouse"]
    B["Feature computation"]
    C["Training dataset"]
    D["Temporal train/validation split"]
    E["Train model"]
    F["Evaluate model"]
    G["Register in MLflow"]
    H["Promote model alias"]
    I["Serving loads selected model"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I

The model lifecycle is:

Train -> Evaluate -> Register -> Promote -> Deprecate

9. Serving Runtime

flowchart TD
    A["FastAPI serving app"]
    B["Request context"]
    C["Redis online state"]
    D["MLflow model artifact"]
    E["FAISS retrieval index"]
    F["Feature services"]
    G["Ranking and post-processing"]
    H["Homepage response"]
    I["Kafka impression event"]

    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    B --> G
    C --> G
    D --> G
    E --> G
    F --> G
    G --> H
    H --> I

The serving path is designed to return a usable homepage even when deeper personalization is not available. Project docs mention these expected failure modes:

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

When that happens, HH-Lion can fall back to safer recommendation strategies instead of failing the homepage request.

10. Main Project Components

11. Infrastructure Used by the Project

12. End-to-End Summary

flowchart TD
    A["User opens homepage"]
    B["Tiger asks HH-Lion for recommendation decisions"]
    C["HH-Lion resolves identity and context"]
    D["HH-Lion retrieves and ranks restaurants"]
    E["Homepage shows ranked results"]
    F["User interactions are tracked"]
    G["Events are validated and stored in ClickHouse"]
    H["Features and datasets are generated"]
    I["Models are trained and evaluated"]
    J["MLflow model alias is promoted"]
    K["Serving uses promoted model and fallback rules"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> D

In one sentence:

HH-Lion connects homepage recommendation serving, user behavior tracking, ClickHouse-backed training data, MLflow model lifecycle, and safe fallback behavior into one recommendation system for Hungry Hub.