Recommendation Implementation Plan

Date: 2026-04-24 Project: hh-lion Related systems:

• hh-felidae: homepage section management and Tiger GraphQL/backend integration
• hh-pegasus: web/mobile frontend homepage rendering and client analytics

Implementation principle: build the smallest measurable recommendation MVP first. Do not invest in complex ML, AI-generated sections, or full homepage automation until tracking, analytics, fallback logic, and A/B testing are production-ready.

1. Project goal

Build a practical, scalable recommendation system that improves Hungry Hub homepage business outcomes while preserving editorial control and operational safety.

Primary business outcomes:

• Sales
• Revenue
• Leads
• Conversion rate
• Booking rate
• User engagement
• Repeat usage

The recommendation system should eventually personalize:

1. Items inside homepage sections
2. Ranking/order of items inside each section
3. Ordering of eligible homepage sections
4. Restaurant, tag, and link sections

However, the MVP should be much narrower:

• Start with homepage recommendations only.
• Start with existing homepage sections only.
• Start with restaurant sections only.
• Start with Recommended For You first.
• Keep hh-felidae as the source of truth for homepage structure.
• Keep hh-pegasus rendering mostly unchanged.
• Use hh-lion as a recommendation decision service, not as a full autonomous homepage generator.

2. MVP scope

The MVP should prove that hh-lion can safely improve homepage business metrics without breaking the existing homepage management and rendering flow.

Included in MVP

1. Existing homepage section integration

   • hh-felidae continues to define which sections exist.
   • hh-lion receives eligible sections and returns item ranking decisions.

2. Recommended For You restaurant section

   • First production recommendation surface.
   • Supports both logged-in users and guests.
   • Falls back safely to existing behavior when recommendations are unavailable.

3. Simple restaurant ranking logic

   • Use available model/session/cohort signals when reliable.
   • Use deterministic fallback when not reliable.
   • Avoid complex new ML until tracking and experiments are ready.

4. Tracking and analytics foundation

   • request_id propagation
   • section-visible events
   • item-visible events
   • click events
   • funnel attribution to package selection, checkout, booking, and revenue

5. A/B testing foundation

   • GrowthBook or equivalent assignment
   • A/A instrumentation test
   • first A/B test for Recommended For You

6. Fallback logic

   • Existing editorial/static behavior remains available.
   • Empty sections should be avoided.
   • Timeout/failure should not break homepage rendering.

7. Basic diagnostics

   • eligibility mode
   • strategy used
   • fallback reason
   • model/ranker version where applicable
   • candidate source counts

3. Non-MVP scope

The following should not be built in the first MVP unless explicitly required after instrumentation is complete.

Excluded from MVP

1. Fully AI-generated homepage sections

   • No dynamic section titles generated by ML/LLM.
   • No arbitrary insertion of new rows without editorial configuration.

2. Full homepage replacement

   • hh-lion should not own the entire homepage layout yet.

3. Global section reordering

   • Do not allow the model to reorder all sections in MVP.
   • Section ordering can come later with pinned/movable zones.

4. Tag and link recommendation models

   • Track tag/link behavior now, personalize later.

5. Complex bandits or reinforcement learning

   • Not before clean item-level exposure and conversion data exists.

6. Heavy model tuning

   • Do not optimize model architecture before attribution and experiment validity are proven.

7. Real-time embedding updates

   • Useful later, not required for MVP.

8. Personalized section title generation

   • Needs editorial QA and localization workflow first.

4. Key assumptions

1. hh-felidae remains the source of truth for homepage section configuration.

2. hh-pegasus should continue rendering existing homepage components wherever possible.

3. hh-lion should return recommendation decisions and item IDs, not complete restaurant display payloads.

4. Tiger/hh-felidae should hydrate recommended item IDs into existing restaurant/tag/link response shapes.

5. For MVP, only restaurant recommendations are productionized.

6. Guest personalization is mostly contextual/session-based, not deep identity-based personalization.

7. Logged-in member personalization depends on available history, model coverage, feature freshness, and fallback behavior.

8. A recommendation system should not be declared successful from offline retrieval metrics alone.

9. Business metrics must be measured from actual homepage exposure, not merely returned API items.

10. Returned impressions and visible impressions are different. Carousel items not seen by users should not be treated as true exposed items.

5. Success metrics

5.1 Primary MVP success metrics

The MVP should be judged mainly by business impact:

• Booking conversion rate per homepage session
• Revenue per homepage session
• Gross booking value per homepage session
• Package selected rate from homepage-exposed restaurants
• Begin checkout rate from homepage-exposed restaurants
• Booking confirmed rate from homepage-exposed restaurants

5.2 Secondary product metrics

• Homepage item visible CTR
• Recommended For You section CTR
• Restaurant detail view rate
• Session depth
• Time to first meaningful click
• Search usage after homepage exposure
• Repeat usage / return rate

5.3 Guardrail metrics

• Homepage latency p95/p99
• hh-lion decision API latency p95/p99
• Empty section rate
• Fallback rate
• Error rate
• Duplicate item rate
• Unavailable/sold-out restaurant exposure rate
• Bounce rate
• Average order value
• Sponsored/editorial section compliance
• Core Web Vitals for web

5.4 Diagnostic metrics

• Percentage of requests by eligibility mode

  • guest_cohort
  • guest_session
  • member_personalized
  • member_personalized_lite
  • cohort_fallback
  • global_fallback

• Candidate source distribution

  • model
  • session
  • cohort
  • editorial
  • static fallback

• Model/ranker coverage

• User not in model mapping rate

• Feature stale rate

• Feature missing rate

• Recommendation timeout rate

6. Required tracking events

Tracking is a prerequisite, not a later enhancement.

6.1 Homepage/request events

• homepage_requested
• homepage_response_returned
• homepage_layout_rendered
• recommendation_decision_returned
• recommendation_fallback_used

6.2 Section events

• section_returned
• section_rendered
• section_visible
• section_click
• section_see_more_click
• section_carousel_scroll

6.3 Item events

• item_returned
• item_rendered
• item_visible
• item_click
• restaurant_detail_view
• favorite_added
• package_selected
• begin_checkout
• booking_confirmed

6.4 Search/context events

• search_submitted
• search_result_clicked
• city_changed
• date_time_changed
• party_size_changed
• filter_applied

6.5 Required event fields

Every recommendation-related event should include as many of the following as applicable:

• event_id
• event_timestamp
• anonymous_id
• user_id
• session_id
• request_id
• surface
• city_id
• country_code
• geo
• language
• device_type
• platform
• referrer_category
• section_id
• section_slug
• section_type
• section_position
• item_id
• item_type
• item_position
• strategy_id
• model_version
• ranker_version
• experiment_key
• experiment_variant
• fallback_reason
• personalization_source
• is_sponsored
• sponsor_name
• package_id
• price_shown
• price_shown_currency
• booking_value

6.6 Important tracking rule

Do not use returned items as the only impression signal.

Track separately:

1. item_returned: item was returned by the backend
2. item_rendered: item was rendered in DOM/component
3. item_visible: item actually entered the viewport
4. item_click: user clicked the item

This distinction is critical for carousel-based ranking and avoiding false negatives.

7. Data requirements

7.1 User/session data

Required:

• anonymous_id
• session_id
• user_id when logged in
• city/country/language/device/platform
• current session views/clicks/searches
• recent homepage section interactions
• membership/history availability

Later:

• cuisine affinity
• price affinity
• location affinity
• dining style affinity
• repeat booking patterns
• favorite restaurants/tags
• session intent embedding

7.2 Restaurant/item data

Required:

• restaurant_id
• branch_id
• city_id
• active/available status
• cuisine
• location
• price tier
• rating/review count
• package availability
• promotion badge
• image/display metadata

Recommended:

• recent impressions
• recent clicks
• recent bookings
• conversion rate
• revenue / booking value
• availability by date/time
• discount/promotion strength
• quality/suppression flags

7.3 Section data

Required from hh-felidae:

• section_id
• section_slug
• section_type
• item_type
• title
• position
• device visibility
• active flag
• template
• groupLandingPageId/tagSectionId/link fields where applicable

New recommendation config:

• personalization_policy
• pinned
• section_reordering_allowed
• allowed_candidate_sources
• min_items
• max_items
• fallback_mode
• metric_goal
• editorial_priority
• experiment_key

7.4 Experiment data

Required:

• experiment_key
• variant
• assignment timestamp
• assignment unit
  • anonymous_id for guests
  • user_id for logged-in users when stable
• exposure event
• conversion events

7.5 Data quality requirements

• Event schemas must be versioned.
• Event timestamps must be reliable.
• request_id must propagate across backend/frontend events.
• Events should deduplicate by event_id.
• Funnel events should be joinable by request_id/session_id/user_id/item_id.
• Event loss should be monitored.

8. Architecture overview

8.1 MVP architecture

hh-pegasus
  -> requests homepage

hh-felidae / Tiger GraphQL
  -> loads editorial homepage sections from db3
  -> identifies sections eligible for recommendation
  -> calls hh-lion recommendation decision endpoint
  -> hydrates recommended item IDs into existing response shape
  -> returns homepage response to hh-pegasus

hh-lion
  -> receives existing section config + user/session/context
  -> decides eligibility
  -> retrieves/ranks restaurant IDs
  -> applies business/fallback rules
  -> returns recommendation decisions + diagnostics

hh-pegasus
  -> renders existing homepage components
  -> disables duplicate client personalization for Lion-served sections
  -> sends visible/click/funnel events

8.2 Recommended service boundary

hh-lion should not return full restaurant card payloads in MVP.

hh-lion should return:

• section_id
• item_id
• item_type
• item_position
• score
• strategy_id
• model_version
• fallback_reason
• diagnostics

hh-felidae/Tiger should hydrate:

• restaurant name
• images
• price
• location
• promotion badge
• translated fields
• links
• existing response attributes

8.3 Fallback model

Fallback hierarchy for MVP:

1. hh-lion personalized decision
2. hh-lion session/contextual decision
3. hh-lion cohort/city popularity
4. existing hh-felidae editorial section items
5. static/global fallback

Homepage must not fail because recommendation fails.

9. Integration with hh-felidae

9.1 Role of hh-felidae

hh-felidae should remain the homepage management and editorial control system.

It should define:

• homepage per city/country/device
• active sections
• section order
• section type/template
• pinned/editorial/sponsored status
• whether each section is recommendation-enabled

9.2 Required hh-felidae changes

Add recommendation configuration to homepage sections.

Potential schema/config fields:

type HomepageSectionRecommendationConfig = {
  personalizationPolicy: "manual" | "recommendation_rank_items" | "recommendation_selected_items";
  pinned: boolean;
  sectionReorderingAllowed: boolean;
  allowedCandidateSources: string[];
  fallbackMode: "editorial" | "cohort" | "global" | "empty";
  minItems: number;
  maxItems: number;
  metricGoal: "booking" | "revenue" | "engagement" | "navigation" | "campaign";
  editorialPriority: number;
  experimentKey?: string | null;
};

For MVP, this can be implemented with minimal fields first:

• personalizationPolicy
• pinned
• sectionReorderingAllowed
• minItems
• maxItems
• experimentKey

9.3 hh-felidae acceptance expectations

• Existing homepage rendering still works when hh-lion is disabled.
• Section configuration can enable/disable recommendation per section.
• Recommended For You can be marked as replace_items.
• Editorial fallback remains available.
• Tiger can pass section config to hh-lion.
• Tiger can hydrate hh-lion item IDs into existing restaurant response shape.

10. Integration with hh-pegasus

10.1 Role of hh-pegasus

hh-pegasus should continue to render homepage sections using existing components wherever possible.

The MVP should avoid a large frontend rewrite.

10.2 Required hh-pegasus changes

1. Accept recommendation metadata in homepage/section responses.

2. Track visible impressions.

3. Track clicks with request_id, section_id, item_id, and strategy_id.

4. Disable duplicate client-side personalization for Lion-served sections.

5. Preserve fallback rendering if recommendation data is missing.

10.3 Recommended frontend response metadata

Each section should expose fields similar to:

type RecommendationMetadata = {
  requestId: string;
  personalizationSource: "editorial" | "pegasus_client" | "lion_server";
  strategyId?: string;
  modelVersion?: string;
  rankerVersion?: string;
  experimentKey?: string;
  experimentVariant?: string;
  fallbackReason?: string | null;
};

10.4 hh-pegasus acceptance expectations

• Homepage renders if recommendation metadata is absent.
• Lion-served Recommended For You does not trigger a second client personalization request.
• item_visible events fire when cards enter viewport.
• click events include request_id and recommendation metadata.
• Existing SEO-critical/static homepage behavior is not broken.

11. Phase-by-phase implementation plan

Phase 1: Discovery and audit

Priority: P0

Objective

Confirm the current data flow, section management model, frontend rendering behavior, event availability, and recommendation failure modes before implementation.

Detailed tasks

1. Audit current homepage section flow in hh-felidae.

   • Identify source tables/models for homepages, homepage_sections, sections, tag sections, link sections, and restaurant sections.
   • Document how city/country/device selection works.
   • Document how section position and active flags work.

2. Audit current homepage rendering in hh-pegasus.

   • Identify all homepage section components.
   • Identify special slug handling such as recommended-for-you and near-me.
   • Identify existing client-side personalization logic.

3. Audit current recommendation API in hh-lion.

   • Document /v2/homepage behavior.
   • Document progressive enhancement/refresh behavior.
   • Document fallback behavior.

4. Audit current tracking events.

   • Identify frontend analytics events.
   • Identify canonical Kafka events.
   • Identify missing item-visible and section-visible events.

5. Audit training data correctness.

   • Verify event names used by ranker extraction.
   • Fix or document mismatches such as add_to_cart/detail_view vs package_selected/view.

6. Produce an implementation decision record.

   • Confirm that hh-felidae owns homepage structure.
   • Confirm that hh-lion is a decision service for eligible sections.

Deliverables

• Architecture decision record
• Current data-flow diagram
• Tracking gap list
• Training data issue list
• Confirmed MVP surface: Recommended For You

Acceptance criteria

• Team agrees on service ownership boundaries.
• Required event and data gaps are documented.
• Recommended For You MVP is approved as first surface.
• Non-MVP items are explicitly deferred.

Dependencies

• Access to hh-lion, hh-felidae, hh-pegasus
• Product/editorial input on homepage section ownership
• Analytics input on event definitions

Phase 2: Tracking and analytics foundation

Priority: P0

Objective

Build trustworthy measurement before launching recommendation changes.

Detailed tasks

1. Define canonical event schema updates.

   • Add or confirm section_visible.
   • Add or confirm item_visible.
   • Ensure click, package_selected, begin_checkout, booking_confirmed include attribution fields.

2. Add request_id propagation.

   • Generate/receive request_id in backend.
   • Include request_id in homepage response.
   • Pass request_id to frontend components.
   • Attach request_id to all homepage events.

3. Add recommendation metadata propagation.

   • strategy_id
   • model_version
   • ranker_version
   • experiment_key
   • experiment_variant
   • fallback_reason

4. Implement frontend visible impression tracking.

   • Track section visibility.
   • Track item card visibility.
   • Avoid firing duplicate visibility events repeatedly for same render.

5. Implement click attribution.

   • Ensure item clicks include section_id, item_id, position, request_id, strategy_id.

6. Validate event pipeline.

   • Confirm events reach Kafka/ClickHouse/analytics destination.
   • Confirm schemas validate.
   • Confirm event counts are plausible.

7. Build initial analytics dashboard.

   • homepage sessions
   • section visible count
   • item visible count
   • item click count
   • package_selected count
   • begin_checkout count
   • booking_confirmed count
   • revenue
   • latency
   • fallback rate

Deliverables

• Updated event contracts
• Frontend tracking implementation
• Backend request_id/metadata propagation
• Analytics dashboard
• A/A test readiness checklist

Acceptance criteria

• item_visible events are captured with section and item positions.
• request_id joins homepage exposure to click/funnel events.
• Event loss is monitored.
• Dashboard can show funnel by section and experiment variant.
• A/A test can be run.

Dependencies

• hh-pegasus analytics implementation
• Kafka/ClickHouse ingestion support
• Analytics/dashboard access

Phase 3: MVP recommendation logic

Priority: P0

Objective

Implement simple, reliable recommendation logic for the Recommended For You restaurant section with safe fallback.

Detailed tasks

1. Define hh-lion section decision API.

   • Add request/response models for section-based recommendation decisions.
   • Accept existing section configuration from hh-felidae.
   • Return ranked item IDs and metadata.

2. Implement eligibility decision.

   • guest_contextual
   • guest_session if session activity exists
   • member_personalized if enough history and model coverage exists
   • member_personalized_lite if model unavailable but history/session exists
   • cohort_fallback
   • global_fallback

3. Implement simple candidate retrieval for MVP.

   • Personalized model candidates when available.
   • Session candidates when available.
   • Cohort/city popularity candidates.
   • Editorial candidate IDs if provided by hh-felidae.

4. Implement simple ranking policy.

   • Prefer model/session candidates for warm users.
   • Use cohort popularity for guests/cold users.
   • Respect business filters.
   • Avoid duplicate restaurants.
   • Keep ranking deterministic for fallback.

5. Implement business filters.

   • Correct city/country.
   • Active restaurant.
   • Available package if availability data is available.
   • Exclude invalid/suppressed restaurants.

6. Implement fallback behavior.

   • If hh-lion fails, use existing editorial data.
   • If candidate count is too low, backfill from cohort/editorial/static fallback.
   • Never return an empty Recommended For You section unless the existing behavior does.

7. Add diagnostics.

   • eligibility_mode
   • eligibility_reason
   • candidate_pool_counts
   • strategy_id
   • fallback_reason
   • latency_ms

8. Fix training/ranker event mismatch.

   • Replace obsolete labels such as add_to_cart/detail_view with canonical events.
   • Use package_selected, begin_checkout, booking_confirmed, view, click as appropriate.

Deliverables

• hh-lion section recommendation decision endpoint
• Eligibility decision logic
• MVP ranking/fallback policy
• Diagnostics payload
• Training data event-name fix
• Unit and integration tests

Acceptance criteria

• Endpoint returns valid ranked restaurant IDs for Recommended For You.
• Endpoint handles guest and logged-in requests.
• Endpoint safely falls back when model/features are unavailable.
• Diagnostics explain why a request was personalized or not.
• No empty section is returned due to recommendation failure.
• Tests cover personalized, guest, cohort fallback, model missing, and timeout paths.

Dependencies

• Phase 1 architecture decision
• Basic section config from hh-felidae or mocked equivalent
• Existing restaurant candidate data
• Existing feature/candidate stores where available

Phase 4: Homepage integration

Priority: P0/P1

Objective

Integrate hh-lion MVP decisions into the real homepage flow without disrupting existing homepage rendering.

Detailed tasks

1. Add minimal recommendation config in hh-felidae.

   • Enable only Recommended For You initially.
   • Add personalization_policy = recommendation_selected_items.
   • Add fallback_mode = editorial/cohort.
   • Add experiment_key.

2. Update Tiger/hh-felidae homepage resolver.

   • Load homepage sections as today.
   • Identify recommendation-enabled sections.
   • Call hh-lion decision endpoint for eligible sections.
   • Merge hh-lion decisions into existing response shape.

3. Hydrate recommended restaurant IDs.

   • Use existing restaurant hydration/OpenSearch logic.
   • Preserve existing Restaurant response schema expected by hh-pegasus.

4. Add fallback merge behavior.

   • If hh-lion times out or fails, return existing section behavior.
   • Log fallback reason.
   • Emit recommendation_fallback_used event or metric.

5. Update hh-pegasus response handling.

   • Accept recommendation metadata.
   • Render existing Recommended For You component.
   • Disable duplicate client-side personalization for Lion-served section.

6. Add end-to-end tests.

   • Recommendation enabled + hh-lion success.
   • Recommendation enabled + hh-lion timeout.
   • Recommendation disabled.
   • Guest request.
   • Logged-in request.

Deliverables

• hh-felidae recommendation config for Recommended For You
• Tiger/hh-felidae integration with hh-lion
• Restaurant hydration path
• hh-pegasus metadata support
• End-to-end integration tests

Acceptance criteria

• Existing homepage still works when hh-lion is disabled.
• Recommended For You can be served by hh-lion when enabled.
• Frontend rendering does not require a new homepage renderer.
• Fallback works on hh-lion failure/timeout.
• Lion-served Recommended For You does not get re-personalized client-side.
• Tracking includes request_id, section_id, item_id, strategy_id, and experiment variant.

Dependencies

• Phase 2 tracking fields
• Phase 3 decision endpoint
• hh-felidae GraphQL/schema updates
• hh-pegasus rendering/tracking updates

Phase 5: Experimentation and measurement

Priority: P0/P1

Objective

Run valid experiments to measure whether recommendations improve business metrics.

Detailed tasks

1. Configure A/A test.

   • Same behavior in both variants.
   • Validate assignment balance.
   • Validate event counts.
   • Validate attribution joins.

2. Define first A/B test.

   • Control: current Recommended For You behavior.
   • Treatment: hh-lion Recommended For You ranking.

3. Define experiment unit.

   • anonymous_id for guests.
   • user_id for logged-in users where stable.
   • Avoid request-level randomization.

4. Build experiment dashboard.

   • Primary business metrics.
   • Secondary metrics.
   • Guardrails.
   • Guest/member split.
   • Device split.
   • City split.

5. Add ramp plan.

   • internal/engineering
   • 1% production
   • 5%
   • 10%
   • 25%
   • 50%
   • 100% only if metrics are healthy

6. Define rollback rules.

   • latency regression
   • fallback spike
   • booking/revenue drop
   • empty section spike
   • frontend error spike

7. Analyze results.

   • Do not rely on CTR alone.
   • Prioritize booking/revenue/session.
   • Separate guest vs member impact.

Deliverables

• GrowthBook experiment configuration
• A/A validation report
• A/B experiment dashboard
• Rollout and rollback runbook
• Experiment readout template

Acceptance criteria

• A/A test shows no instrumentation bias.
• A/B test can attribute funnel outcomes to homepage recommendation exposure.
• Guardrails are monitored during rollout.
• Rollback can be executed quickly.
• Decision criteria are agreed before reading results.

Dependencies

• Phase 2 tracking complete
• Phase 4 integration complete
• Analytics dashboard available
• GrowthBook or experiment system available

Phase 6: Improved personalization

Priority: P1/P2

Objective

Expand from Recommended For You MVP into broader, better personalization after measurement is proven.

Detailed tasks

1. Add member personalization tiers.

   • new logged-in member
   • light-history member
   • warm member
   • high-confidence member

2. Add personalized-lite fallback.

   • Use recent views/bookings/favorites when model mapping is unavailable.
   • Avoid direct fallback from warm member to generic cohort.

3. Improve guest personalization.

   • Use session views/clicks/searches.
   • Use city/language/device/time/referrer.
   • Use location when permitted.

4. Expand to selected restaurant sections.

   • Start with rerank_items only.
   • Preserve existing editorial candidate pool.
   • Do not replace items until reranking proves safe.

5. Add section-specific policies.

   • Recommended For You
   • Trending Near You
   • Deals
   • New Arrivals
   • Based on Your Taste

6. Improve ranker features.

   • item conversion rate
   • booking value
   • availability
   • price tier affinity
   • cuisine affinity
   • location affinity
   • session intent

7. Add better offline evaluation.

   • Temporal split.
   • Production-serving parity.
   • Section-level metrics.
   • Funnel-weighted labels.

Deliverables

• Personalization tier logic
• Personalized-lite fallback
• Reranking support for selected restaurant sections
• Section policy framework
• Improved ranker features/evaluation

Acceptance criteria

• Warm users do not unnecessarily fall back to generic cohort.
• Guest/session recommendations respond to current behavior.
• Additional restaurant sections can be reranked safely.
• Offline metrics correlate better with online results.
• Business guardrails remain healthy.

Dependencies

• Successful MVP experiment or clear learning
• Reliable item-level tracking history
• Feature availability in ClickHouse/Redis/feature store
• Product agreement on eligible sections

Phase 7: Advanced recommendation system

Priority: P2/P3

Objective

Evolve the MVP into a scalable recommendation platform for restaurants, tags, links, section ordering, and controlled AI-generated experiences.

Detailed tasks

1. Add bounded section ordering.

   • Define pinned zones and movable zones.
   • Only reorder eligible non-pinned sections.
   • Preserve editorial/sponsored constraints.

2. Add tag recommendations.

   • Track tag impressions/clicks/navigation value.
   • Rank tags based on session/member/context.
   • Optimize for downstream restaurant discovery and bookings.

3. Add link/campaign recommendations.

   • Track link impressions/clicks/conversions.
   • Respect campaign priorities and sponsorship rules.
   • Rank links by business objective.

4. Add controlled replacement mode.

   • Allow selected sections to replace editorial items.
   • Require personalization_policy = recommendation_selected_items.
   • Keep fallback to editorial section.

5. Add generated sections.

   • Only in configured slots.
   • Require editorial approval/preview.
   • Support localization.
   • Add safety and brand constraints.

6. Add exploration/bandit layer.

   • Exploration budget for new restaurants.
   • Avoid popularity feedback loops.
   • Consider contextual bandits after enough clean exposure data exists.

7. Add real-time personalization improvements.

   • More responsive session embeddings.
   • Faster feature updates.
   • Better cold-start handling.

8. Add multi-objective optimization.

   • Booking probability
   • Revenue
   • Engagement
   • User satisfaction
   • Supplier fairness
   • Editorial/campaign constraints

Deliverables

• Section ordering system
• Tag/link recommenders
• Controlled replacement mode
• AI-generated section framework
• Exploration/bandit framework
• Advanced model evaluation/promotion workflow

Acceptance criteria

• Section ordering improves business metrics without hurting editorial commitments.
• Tag/link recommendations show measurable downstream value.
• AI-generated sections are safe, localized, and editorially controlled.
• Exploration improves new item exposure without harming conversion.
• Model promotion is based on online and offline evidence.

Dependencies

• Strong tracking foundation
• Multiple successful A/B tests
• Sufficient data volume
• Editorial tooling and approval workflow
• Mature model monitoring and rollback

12. Risks and mitigations

Risk 1: Optimizing clicks instead of bookings/revenue

Mitigation:

• Use booking/revenue per homepage session as primary metrics.
• Treat CTR as secondary.
• Track full funnel attribution.

Risk 2: Weak or missing item-level impressions

Mitigation:

• Implement item_visible tracking before A/B testing.
• Distinguish returned/rendered/visible/clicked.

Risk 3: Recommendation breaks editorial control

Mitigation:

• hh-felidae remains source of truth.
• Add pinned/section_reordering_allowed/personalization_policy fields.
• Do not allow full layout generation in MVP.

Risk 4: Frontend duplicate personalization conflicts with hh-lion

Mitigation:

• Add personalizationSource and disableClientPersonalization.
• Ensure Lion-served sections are not re-ranked again in Pegasus.

Risk 5: Empty or low-quality sections during failures

Mitigation:

• Always keep editorial fallback.
• Add static/global fallback.
• Monitor empty section rate and fallback rate.

Risk 6: Offline model improvements do not improve homepage outcomes

Mitigation:

• Evaluate serving path, not only retrieval model.
• Use online A/B tests for promotion decisions.
• Add stage-level diagnostics.

Risk 7: Cold-start guests receive generic/popularity-biased results

Mitigation:

• Use contextual/session signals.
• Add exploration budget later.
• Monitor exposure concentration.

Risk 8: Members silently fall back to cohort

Mitigation:

• Add explicit eligibility diagnostics.
• Add personalized-lite fallback.
• Monitor user_not_in_model_mapping and feature_stale rates.

Risk 9: Latency hurts conversion

Mitigation:

• Strict timeout for hh-lion calls.
• Cache safe fallbacks.
• Keep SSR/rendering path stable.
• Monitor p95/p99 latency.

Risk 10: AI-generated sections create brand/legal/localization issues

Mitigation:

• Keep out of MVP.
• Require editorial approval workflow before launch.
• Add sponsorship/DSA labeling rules.

13. MVP definition of done

The MVP is done only when all of the following are true.

Product scope

• Recommended For You is the only production recommendation surface.
• The MVP supports restaurant recommendations only.
• hh-felidae remains source of truth for homepage layout.
• hh-pegasus renders using existing homepage components.

Tracking

• request_id is propagated from backend response to frontend events.
• section_visible is tracked.
• item_visible is tracked.
• item_click is tracked.
• package_selected, begin_checkout, and booking_confirmed can be attributed to homepage exposure.
• Events include section_id, item_id, positions, strategy, and experiment variant.

Recommendation behavior

• hh-lion can return Recommended For You ranked restaurant IDs.
• Guest requests receive safe contextual/cohort recommendations.
• Logged-in member requests use personalization when eligible.
• Fallback works when hh-lion/model/features fail.
• Empty sections are avoided.
• Diagnostics explain eligibility and fallback.

Integration

• hh-felidae can enable/disable recommendation for Recommended For You.
• Tiger/hh-felidae can call hh-lion and hydrate recommended restaurant IDs.
• hh-pegasus can render Lion-served Recommended For You.
• Pegasus does not duplicate client-side personalization for Lion-served section.

Experimentation

• A/A test has passed.
• First A/B test is configured.
• Dashboard shows primary, secondary, and guardrail metrics.
• Rollback rules are documented.

Operational readiness

• Errors and fallback rates are monitored.
• Latency p95/p99 is monitored.
• There is a runbook for disabling hh-lion recommendation integration.
• Existing homepage behavior remains available as fallback.

14. Immediate next steps

1. Review and approve this plan with product, backend, frontend, data, and editorial stakeholders.

2. Create an architecture decision record confirming:

   • hh-felidae owns homepage structure.
   • hh-lion owns recommendation decisions.
   • hh-pegasus owns rendering and visible/click tracking.

3. Define the exact /v2/homepage/decide contract.

4. Add minimal recommendation config to hh-felidae for Recommended For You.

5. Implement item_visible and section_visible tracking in hh-pegasus.

6. Fix event-name mismatch in hh-lion ranker training extraction.

7. Build and test the Recommended For You MVP behind an experiment flag.

8. Run A/A test before any A/B recommendation test.

15. Final guidance

Keep the first version boring and measurable.

The system should first prove that it can safely improve one existing section with clean attribution and fallback. Only after that should it expand to more sections, more item types, section ordering, generated sections, bandits, and advanced ML.

The correct sequence is:

1. Tracking
2. Fallbacks
3. One-section MVP
4. A/A validation
5. A/B measurement
6. Broader restaurant section reranking
7. Section ordering
8. Tags and links
9. AI-generated sections
10. Advanced ML and bandits

Do not reverse this order.