# Slaapstad - Vacation Rental Platform

## Overview
Slaapstad is a South African vacation rental platform designed to connect guests with diverse properties and offer hosts comprehensive management tools. It aims to be the leading local solution, providing features for various property types (standard rentals, multi-room B&Bs, campsites), advanced calendar management, and integrated local payment options. The platform focuses on user engagement through a loyalty program and personalized experiences.

## User Preferences
- Use South African spelling throughout (favourite not favorite)
- No emojis in UI
- Clean, modern design following design_guidelines.md
- South African focus (properties in Cape Town, Johannesburg, etc.)

## System Architecture
The platform features a React, TypeScript, Vite, TailwindCSS, and Shadcn UI frontend, communicating with an Express.js and TypeScript backend using an in-memory data store. TanStack Query manages state, and Wouter handles routing.

**Key Design Decisions & Features:**
- **UI/UX:** Supports dark/light themes with a clean, modern aesthetic.
- **Property Management:** Hosts can list and manage diverse properties, including those without street addresses. Properties are graded using a moon system with type-specific rating criteria and support detailed amenities.
- **Availability & Booking:** An advanced booking system includes host-managed calendars, custom pricing, notice periods, and iCal integration for external syncing. Hosts can edit upcoming bookings, and guests can specify arrival times.
- **Multi-Room & Campsite Support:** Accommodates complex property types like B&Bs with multiple room types and campsites with available sites, each having distinct inventory, pricing, and amenities.
- **Property Types & Subtypes:** Extensive property type definitions including hotels, lodges, campsites, boats, glamping, and unique stays, each with specific attributes.
- **Expanded Amenities:** A wide range of amenities across multiple categories including family, boat/marina, glamping, and hotel services.
- **Room-Level Features:** Detailed specifications for individual rooms including type, bathroom, view, and accessibility.
- **User Engagement:** Includes a new user onboarding flow, Zzz rewards loyalty program (earn 2% as Zzz's, redeem at Zzz Partner properties), property favouriting, and a review system for both guests and hosts.
- **Host Dashboard:** Centralized area for hosts to manage properties, bookings, and receive notifications.
- **Discounts:** Supports weekly stay discounts and integrates with the Zzz loyalty program.
- **First Booking Free Promotion:** A promotional offer for new listings to encourage adoption.
- **Financials:** Features PDF invoice generation, a commission-based payout system for hosts, guest refunds with an admin fee, and host cancellation penalties.
- **Search:** Robust search capabilities with filtering options, location-based searching, and persistence of search parameters.
- **Contact Form:** Allows users to send messages, which are stored and viewable in the admin panel.
- **Site Visitor Analytics:** Tracks unique daily visitors for administrative insights.
- **Referral System:** Enables users to generate and share referral codes, earning Zzz rewards for successful referrals.
  - **New User Splash:** First-time users see a referral program splash screen after completing profile registration, explaining the R1000 earning potential.
- **Zzz Rewards Program:** Comprehensive monetary-based loyalty program:
  - **Exchange Rate:** 1 Zzz = R1 (simple 1:1 ratio)
  - **Earning:** Guests earn 2% of booking value as Zzz (excluding service fees), credited 7 days after checkout
  - **Referral Bonuses:** Referrer gets 50 Zzz (R50), referee gets 25 Zzz (R25) on signup (no booking required), max 40 referrals per month (R2000 potential)
  - **Redemption:** Minimum 10 Zzz (R10), fixed 50% max redemption tier for all Zzz Partners, 100% host-funded redemption
  - **Host Compensation:** When guests redeem Zzz, hosts receive those Zzz in their wallet (offset for listing price discount)
  - **Commission Calculation:** Commission is calculated on original price before Zzz discount is applied
  - **Zzz Partner Program:** Properties can opt-in to accept Zzz redemptions with fixed 50% max redemption (hosts cannot choose percentage)
  - **Transaction Tracking:** Full history with balanceBefore/balanceAfter for audit trail
  - **Wallet API:** Endpoints for balance, pending credits, transaction history, redemption preview
  - **Cron Jobs:** Daily 4am processing of pending Zzz credits for completed bookings
- **Emergency Services Directory:** Provides a directory of national and provincial emergency contacts.
- **Property Translations:** Supports multi-language translations for property details.
- **Water/Power Security Badges:** Visual indicators for properties with water and power backup amenities.
- **Hidden Gems Feature:** A geolocation-based algorithm to discover and highlight unique, undiscovered properties based on multiple scoring criteria and configurable administrative settings.
- **Authentication:** Uses Google OAuth 2.0 for secure user login and session management.
- **Search Ranking Algorithm:** A hybrid scoring algorithm with strict geographic fairness:
  - **Three-Tier Geographic System:** Tier 0 (verified in-area with coordinates) always ranks first, Tier 1 (text-matched without coordinates) second, Tier 2 (out-of-area) last. Commission tiers cannot override geographic ordering.
  - **Dynamic Relevance Radius:** City searches (10km), coastal destinations (25km), road trips/routes (50km), safari/wilderness (75km).
  - **Score Weights:** Distance (65%), recommendation score (15%), location match (10%), SA-specific intent matching (10%).
  - **Recommendation Score Weights:** Review quality (30%), conversion rate (25%), predicted satisfaction (15%), availability (10%), cancellation reliability (10%), local engagement (5%), guest personalization (5%).
  - **Diversity Boost:** 15% of searches surface underrepresented properties (new, rural, low-review with 4.0+ rating) at positions 3-7, with top 2 positions protected.
  - **Grace Period:** New properties receive reduced review weight penalty (0-3 months: 15% weight, 3-6 months: 22.5% weight).
  - **Commission Visibility Boost:** 9% tier: 0%, 14% tier: 22%, 19% tier: 50%, 24% tier: 80% - cannot override geographic fairness.
  - **"Most Relevant" Sort:** Zero-commission-influence sort option using pure quality signals (rating 60%, review count 40%) + distance proximity for location searches.
  - **Featured Badge:** "Featured" badge shown ONLY for active boost campaigns (boostActive=true), not for commission tier alone.
  - **SA Intent Matching:** Boosts loadshedding-proof, pet-friendly, braai, eco-certified, and water security features when matching search intent.
  - **Zzz Partner Boost:** Active Zzz Partners receive a 20% ranking boost in search results for offering 50% guest discounts.
  - **Host Transparency:** `/api/host/properties/:id/rank-breakdown` endpoint provides score components, weights, and improvement tips.
- **ML Ranking Infrastructure:** Foundation for machine learning-driven ranking:
  - **A/B Testing:** Experiment framework with weighted variant assignment, consistent user bucketing, and guardrails.
  - **Feature Collection:** Rich feature payloads (40+ features) stored for ML training including distance, reviews, price, intent match.
  - **Metrics Monitoring:** Daily aggregation of NDCG@10/20, MRR, CTR, conversion rate, host diversity, and tier fairness.
  - **Model Interface:** Pluggable model system with heuristic fallback, supports pointwise (LightGBM) and pairwise (LambdaMART).
  - **Admin Endpoints:** `/api/admin/experiments` for A/B test management, `/api/admin/ml-metrics/summary` for monitoring dashboard.

## External Dependencies
- **Google Maps API:** Used for geo-coding and location services, especially for rural properties.
- **Yoco Payment Gateway:** Integrated for secure processing of card payments, Apple Pay, and Google Pay through a popup SDK.
- **Twilio SMS Notifications:** Utilized for sending booking-related SMS notifications to both guests and hosts.
- **iCal:** Supports calendar synchronization with external booking platforms.
- **Property Import:** System for importing property listings from Airbnb and LekkeSlaap, including detailed information, amenities, and property-type-specific fields via text analysis.