Restaurant Prioritization
Welcome! This documentation explains how Hungry Hub automatically scores, ranks, and categorizes restaurant partners so that our marketing and account management teams can focus their time and budget where it makes the biggest impact.
📌 TL;DR: What Is This Project?
Hungry Hub partners with thousands of restaurants. Marketing resources—like Facebook ads, influencer (KOL) reviews, push notifications, and newsletter blasts—are limited.
In the past, deciding which restaurant to promote often relied on manual requests or intuition. Restaurant Prioritization replaces guesswork with data:
- Pulls Fresh Data: Connects to ClickHouse every week to gather bookings, dining revenue, ad spend, and promotion history.
- Predicts Organic Demand: Uses machine learning (LightGBM) to forecast how much baseline revenue a restaurant generates without heavy marketing.
- Segments the Portfolio: Places each restaurant into one of 4 clear action groups (e.g., Promote More, High Risk, Core Revenue Drivers, or Deprioritize).
- Delivers an Interactive Dashboard: Gives marketers and managers an easy-to-use Streamlit dashboard with smart filters, ready-to-run marketing lists, and budget simulation.
flowchart LR
A["ClickHouse Data<br/>(Bookings, Ads, KOL)"] --> B["Machine Learning<br/>(LightGBM core_v2)"]
B --> C["Priority Scoring &<br/>4 Business Segments"]
C --> D["Streamlit Dashboard<br/>(Rankings & Simulator)"]
D --> E["Marketing Campaigns<br/>(FB, KOL, App Blasts)"]
🗺️ Documentation Directory
This documentation is split into 6 bite-sized chapters. Read what you need based on your role:
| Chapter | Title | Who Should Read This? | What You Will Learn |
|---|---|---|---|
| 01 | Overview & Restaurant Universe | Everyone / Beginners | The big picture, the end-to-end flow, and the breakdown of all 7,400+ restaurants. |
| 02 | Business Context & Strategy | Marketers, Campaign Managers, Executives | The 3 core business questions, the 4 segments, badges, and marketing priority logic. |
| 03 | Architecture & Data Pipeline | Data Engineers, Analytics Engineers | Data tables in ClickHouse, the mandatory 7-condition booking rule, and clean revenue rules. |
| 04 | Machine Learning Pipeline | Data Scientists, ML Engineers | LightGBM model (core_v2), feature engineering, data leakage prevention, and SHAP explainability. |
| 05 | Dashboard User Guide | Marketing Specialists, Account Managers | How to navigate the 4 dashboard tabs, use sidebar filters, and export target lists. |
| 06 | Operations & SRE Runbook | SREs, DevOps, Platform Engineers | Cron schedules, dedicated GitHub Actions runner, Kubernetes setup, health checks, and rollback. |
📖 Quick Glossary (Key Terms Made Simple)
If you are new to restaurant analytics or Hungry Hub, here are the most common terms:
- GMV (Gross Merchandise Value): The total value of confirmed dining reservations in Thai Baht (฿). We only count net revenue from confirmed, non-canceled bookings (
total_price_v2_cents / 100.0). - Covers: The total number of dining guests (seats booked). A reservation for 4 people equals 4 covers.
- Bookable Restaurant: A partner whose profile is active, has active dining packages/deals, and can currently accept reservations on the Hungry Hub app or website.
- Under-Promoted: A restaurant that performs strongly (high customer ratings, good conversion) but hasn’t received marketing support recently. These are our “hidden gems.”
- Over-Promoted: A restaurant that received heavy ad spend or influencer coverage, but generated poor bookings in return.
- KOL (Key Opinion Leader): Food bloggers, TikTok creators, and social media influencers who review Hungry Hub partner restaurants.
- Sent Count: For non-monetary marketing (like App Push Notifications and Email Blasts), we track the number of campaigns sent (e.g., “12 Sent”) rather than a monetary cost.
- LightGBM: The high-speed machine learning model that learns historical booking patterns to predict expected revenue.
🚦 System Status & Maintenance
- Production Repository:
hungryhub-team/restaurant-prioritization - Deployment Platform: Kubernetes (K8s) Cluster via Docker & GitHub Container Registry (
ghcr.io) - Dashboard URL: Internal company VPN (Streamlit application)
- Update Frequency: Weekly batch run every Monday morning; monthly full historical retraining
- Point of Contact: Data & Machine Learning Team (
#data-teamon Slack)