docs/prd_design_spec.md

# Product Requirements Document (PRD) & God-Level Design Spec
## HyperFlow 3.0: Zomato District-Style Premium Food & Nightlife Commerce Engine

This document provides the complete, production-grade specification for the **HyperFlow 3.0** platform. It details our "god-level" system architecture, color tokens, and exact UI layouts for all **16 screen permutations** to ensure a high-fidelity visual experience and recruiter-shocking engineering depth.

---

## 1. System & Architecture Specification (The "God-Level" Upgrade)

### A. Scalability & High-Concurrency Transaction Engine
1. **Double-Layer Locking Pipeline**:
   - **Primary Lock (In-Memory)**: Redis `SETNX` key checkout with custom token signatures. Key TTLs are strictly bounded (default `5000ms`) to prevent deadlocks.
   - **Unlock Safeguard**: Evaluated via atomic Redis Lua scripts ensuring that only the original thread owner can release its lock.
   - **Fail-Safe Database Row Lock**: PostgreSQL `SELECT FOR UPDATE NOWAIT` is queried if Redis is unreachable or if inventory verification falls back to the database. Thread pools fail-fast immediately with an `HTTP 409 Conflict` rather than queuing under contention, avoiding connection starvation.
2. **Transactional Outbox Event Sourcing**:
   - Instead of direct dual-writes to PostgreSQL and Apache Kafka, events are written to an `outbox` database table within the same ACID transaction.
   - A separate CDC (Change Data Capture) polling daemon tails the outbox table and streams events to Kafka topic `hyperflow.orders.telemetry` with at-least-once delivery guarantees.
3. **Strict Session Pooling & Keep-Alives**:
   - Enforce SQLAlchemy pool recycling (`pool_recycle=1800`), overflow constraints (`max_overflow=10`), and size limits (`pool_size=20`) to handle high-frequency active connections without leakage.

### B. Machine Learning & Predictive Pipeline
1. **Tobit Type I MLE Demand Forecaster**:
   - Corrects for stockout data censoring. Incorporates historical demand bounds. If a product sells out, real demand is treated as right-censored: $y \ge y_{\text{observed}}$.
   - Implements optimization via SciPy's L-BFGS-B algorithm initialized using Heckman's two-step estimator for rapid convergence in production ASGI loops.
2. **Cox Proportional Hazards Store Churn Estimator**:
   - Monitors dark store lifetime profitability metrics based on covariates: average order value (AOV), user complaints ratio, and local density competition.
3. **Active Anomaly Detection & PSI Monitoring**:
   - Population Stability Index (PSI) calculations run continuously on sliding windows of input features (ambient temperature, rainfall intensity, order volume).
   - If PSI exceeds $0.20$ (indicating significant drift), a background task compiles new LightGBM prediction trees and updates reference distributions automatically.

---

## 2. UI/UX Design System (Zomato District Aesthetics)

- **Theme**: Premium Midnight Dining & Nightlife (Neon Accent-Heavy Dark Mode).
- **Background (Surface)**: `#040406` (Deep Space Obsidian Black).
- **Primary Accent**: `#FF0077` (District Crimson / Hot Pink Glow).
- **Secondary Accent**: `#8F00FF` (Neon Indigo / Rave Violet).
- **Success Mint**: `#00E676` (Neon Green).
- **Warning Amber**: `#FFB300` (Surge / Low Stock).
- **Typography**:
  - Headings: *Outfit* (Inter-spaced, bold, wide display weight).
  - Metrics & Numbers: *JetBrains Mono* (Semi-bold, crisp monospace).

---

## 3. Screen Permutations & Layout Specifications (All 16 Screens)

```mermaid
graph TD
    A[Login / Verification Screen] --> B[Multi-Cuisine Feed & Hub]
    B --> C[Restaurant Details & Menu View]
    B --> G[Quick Tab Grocery Console]
    B --> J[Dineout Booking Calendar]
    C --> D[Active Cart & Checkout Drawer]
    D --> E[Live Delivery Tracker & Map]
    B --> F[Admin Operations Dashboard]
    F --> H[System Telemetry Panel]
    F --> I[ML Guard & Dispute Triage]
```

### 1. Splash & Onboarding Screen
- **Visuals**: Full-screen deep radial gradient (`#040406` to `#FF0077` at 15% opacity). Features the animated "HF" logo monogram with a particle glow.
- **Interactivity**: Lottie-based onboarding carousel illustrating Food, Instamart, and Dineout operations. "Continue with Phone" triggers active slide transitions.

### 2. Login & Phone OTP Verification Screen
- **Visuals**: Centered glassmorphic modal with a pulsing neon pink border (`box-shadow: 0 0 15px rgba(255,0,119,0.3)`).
- **Interactivity**: Numeric keypad inputs for 10-digit mobile number, transitioning into 4-digit OTP slots with active countdown timers.

### 3. Multi-Cuisine Discovery Hub (Home Feed)
- **Visuals**: Wide display headers, horizontal scrolling cuisine list, bento-grid cuisine categories.
- **Interactivity**: 
  - Tapping Address triggers address dropdown populated dynamically from the Swiggy `get_addresses` API.
  - Features the "Weekly Streak Challenge" progress indicator showing completed orders.
  - "AI Recommended Pick of the Day" shows a customized restaurant card with an `🤖 AI recommended` glowing chip.
  - Veg-only filter toggles list results instantly with haptic-scale transitions.

### 4. Search & Autocomplete Screen
- **Visuals**: Glassmorphic search field with a blinking cursor. Shows "Trending Searches" as glowing outline tags.
- **Interactivity**: Typing executes a debounced (50ms) API call fetching dish-level and restaurant-level matches.

### 5. Restaurant Detail Page
- **Visuals**: Full-bleed hero banner representing gourmet cuisines. Sticky header appears on scroll with search and share shortcuts.
- **Interactivity**: Tapping menu category badges scrolls the view smoothly to corresponding sections. Displays dynamic calorie/protein counts per item.

### 6. Detailed Cart Drawer
- **Visuals**: Glassmorphic bottom drawer (`backdrop-filter: blur(20px)`) overlaying the menu.
- **Interactivity**: Items list with increment/decrement controls, active delivery mode toggle (Eco EV vs Normal), and the circular **AI Nutrition Progress Ring** showing macro targets (protein/carbs/fat).

### 7. Interactive Offers & Coupons Drawer
- **Visuals**: List of cards detailing promo codes (`DIWALI50`, `HYPERPRO`, `FREEFEES`) with active borders.
- **Interactivity**: Selecting a coupon recalculates delivery fees, taxes, and platforms fees dynamically with a text verification alert.

### 8. Secure Payment Selection
- **Visuals**: Premium wallet style icons representing Google Pay, Paytm, Visa, and co-branded cards.
- **Interactivity**: Confirming payment triggers a fullscreen color confetti explosion (`canvas-confetti`) celebrating successful checkout.

### 9. Active Delivery Tracker (Leaflet Map)
- **Visuals**: Map layout rendering dark Carto Tiles. Renders a dotted route polyline and a scooter marker smoothly interpolating coordinates.
- **Interactivity**: Live Rider HUD displays rider speed in `m/s` (JetBrains Mono) and ambient weather sensors.

### 10. AI Agent Chat Console
- **Visuals**: Typewriter chat feed. Shows tool executions as glass badges (e.g., `search_menu()`, `book_table()`) illustrating system transparency.
- **Interactivity**: Typing dietary goals (e.g. "high protein under ₹250") parses menus and appends cards directly.

### 11. Dineout Slot Booking Calendar
- **Visuals**: Swipeable gallery cards for premium hotels (e.g. Mayfair Lagoon) showing rating badges and costs.
- **Interactivity**: Active slot booking calendar showing available timings (e.g. "08:30 PM") and guest counts.

### 12. System Telemetry Panel (Control Room)
- **Visuals**: Recharts-based double AreaChart displaying live feature drift indices (PSI) and outbox event sizes.
- **Interactivity**: "Inject Drift" and "Trigger Retrain" buttons simulate pipeline failures and rebuild LightGBM trees.

### 13. Restaurant SLA & Order Prep Dashboard (Control Room)
- **Visuals**: Grid of preparation orders showing timer bounds. Status bars turn red as limits approach.
- **Interactivity**: "Ready for Pickup" button releases the Redis/PostgreSQL inventory hold and updates the outbox queue.

### 14. Dark Store Picking Console (Control Room)
- **Visuals**: Table listing order SKUs with aisle locations (e.g. Aisle 5, C3) to simulate physical picking.
- **Interactivity**: "Mark Packed" checkbox increments warehouse throughput metrics.

### 15. Rider Logistics & Dispatch Tracking (Control Room)
- **Visuals**: Geospatial map showing all active dispatch nodes.
- **Interactivity**: Updates coordinates automatically using WebSocket streams.

### 16. ML Guard / Refund Triage Console (Control Room)
- **Visuals**: Data tables highlighting customer claims, original order amounts, and fraud probabilities.
- **Interactivity**: "Approve Refund" triggers semantic match checks and flags anomalies.

---

## 4. Verification & Test Suite Strategy

### A. Unit Tests
- Execute `python -m unittest discover -s tests -p "test_*.py"` to verify core regression equations, fraud plausibility filters, and dispatch SLA limits.
- Assert that Tobit model imputations always evaluate $\ge$ observed stockout numbers.

### B. Manual Verification Steps
1. Re-run `docker compose -f docker-compose.prod.yml up -d --build` to ensure all containers launch cleanly with zero compilation warnings.
2. Hit `http://localhost/` in the browser and navigate through the different screens to verify that smooth transitions compile perfectly.