Hugging Face's logo

Spaces:
Gaurav711
/
HyperFlow
Sleeping

App Files Community
HyperFlow / docs /prd_design_spec.md
Gaurav711's picture
Gaurav711
deploy: revert to 733e96b
d491dc1
preview code
|
Raw
History Blame Contribute Delete
9.39 kB

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) 

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.