PreFill is a brand-agnostic feature extension & SDK module designed for quick commerce platforms. Built with FastAPI, Next.js, Facebook Prophet, PostgreSQL, and LangGraph, PreFill turns reactive quick commerce apps into proactive, automated replenishment engines.
PreFill watches how your household consumes groceries over time, learning your patterns (such as milk, atta, oil, bread, and egg consumption velocity) using Prophet forecasting models. It proactively notifies you over WhatsApp 2 days before items deplete, letting you restock via a stateful LangGraph agent in one tap. It also features price tracking and recipe-to-cart pantry intelligence.
Why this project? Quick commerce platforms compete on 10-minute delivery, identical stock, and price parity. PreFill builds a household-specific intelligence profile that acts as a structural lock-in moat across any quick commerce provider.
| Status | Feature | Description |
|---|---|---|
| ✅ | Time-Series Consumption Modeling | Uses Facebook Prophet to build per-item consumption baselines, calculating average daily usage, cycle days, and depletion countdowns. |
| ✅ | Brand-Agnostic SDK Architecture | Zero platform binding. Built as an embeddable tab extension compatible with any quick commerce provider. |
| ✅ | Single Unified Mobile Tab | Integrates Smart Pantry Depletion, Recipe Ingredient Checker, and Market Price Signals into a single scrollable feed inside the PreFill host tab. |
| ✅ | iPhone 16 Pro Hardware Mockup | Rendered in exact 71.5mm × 149.6mm physical hardware proportion (w-[305px] aspect-[71.5/149.6]) with Dynamic Island and ultra-thin titanium bezel. |
| ✅ | Predictive WhatsApp Restock Agent | Triggers stateful LangGraph dialogues via WhatsApp API, allowing users to build carts and checkout in one tap. |
| ✅ | Pantry-Aware Recipe Planner | Extracts ingredients from user recipe queries, checks estimated remaining pantry quantities, and bundles only missing items into the cart. |
| ✅ | Commodity Price Intelligence | Tracks tomatoes, onions, oil, atta, and milk in PostgreSQL time-series logs, alerting users on spikes/dips and offering substitutions. |
| ✅ | Lifestyle Anomaly Filtering | Automatically filters out outlier events like travel gaps (predictions paused) and guest spikes so forecasting stays highly accurate. |
| ✅ | Interactive Demo Scenario Switcher | Collapsible control panel lets reviewers hot-swap between Standard Staples, Weekend Party, and Vacation Mode scenarios — regenerates seed data and rebuilds Prophet models on the fly. |
| Layer | Technology | Purpose |
|---|---|---|
| Language | Python / TypeScript | Python for ML models & backends; TypeScript for responsive dashboards |
| Framework | FastAPI & Next.js 16 | Asynchronous API handlers (AsyncSession SQLAlchemy); Next.js App Router |
| Styling & Design | Tailwind CSS v4 & Emil Kowalski Principles | Apple/Linear typography system (Outfit + Cambo), 160ms micro-interactions, clean Lucide icons |
| ML / Agents | Facebook Prophet & LangGraph | Time-series consumption forecasting & stateful multi-turn restock agent with PostgreSQL checkpointer |
| Database | PostgreSQL | Relational storage for inventory logs, household profiles, and agent checkpoints |
| Testing | Pytest & Next Build | Automated test suite (16/16 passing tests) & zero-error TypeScript builds |
flowchart LR
A[Host Quick Commerce App] --> B[PreFill SDK Tab]
B <--> C[FastAPI Backend Engine]
C <--> D[PostgreSQL DB]
C <--> E[Prophet Forecaster]
C <--> F[LangGraph WhatsApp Agent]
PreFill/
├── backend/ # FastAPI Python Backend
│ ├── main.py # FastAPI application setup
│ ├── agents/ # LangGraph agents (restock_agent.py, price_agent.py, recipe_agent.py)
│ ├── api/routes/ # REST API endpoints (orders.py, predictions.py, prices.py, recipes.py, restock.py)
│ ├── database/ # Connection pool & AsyncSession models (models.py, connection.py)
│ ├── ml/ # Machine Learning models (consumption_model.py, anomaly_detector.py, confidence_scorer.py)
│ ├── notifications/ # WhatsApp runner & scheduler (whatsapp.py, scheduler.py)
│ ├── mcp/ # Quick Commerce MCP client & mock server (client.py, mock_server.py)
│ ├── seed/ # Seed data generators & scenario switcher (catalog.py, generate_orders.py, scenarios.py)
│ └── tests/ # 16 automated pytest unit & integration test files
│
├── frontend/ # Next.js 16 Responsive Showcase App
│ ├── app/ # App router (page.tsx, layout.tsx, globals.css)
│ ├── components/ # PhoneMockup.tsx, Header.tsx, ExecutivePanel.tsx, ui/iphone.tsx
│ └── lib/ # API client wrappers & TypeScript definitions
│
├── CLAUDE.md # Project rules & session resume tracking
├── CONTEXT.md # Domain glossary & business rules
├── ARCHITECTURE.md # Full technical blueprint
└── README.md # Master project overview
To keep the application highly responsive, low-latency, and production-ready:
- Asynchronous Thread Offloading: Heavy time-series model fitting (Facebook Prophet) and external API calls (Twilio) are offloaded to background threads using
asyncio.to_thread. This ensures FastAPI's event loop is never blocked. - GZip Payload Compression: Backed by FastAPI's
GZipMiddlewareto compress API payloads, saving network bandwidth and speeding up client load times. - Smart Client Caching (SWR): Utilizes Next.js
swrfor data fetching. Implements cache-first loading, deduplication of concurrent requests, and silent revalidation to deliver instantaneous tab transitions (<10ms). - HTTPX Connection Pooling: The quick commerce MCP client utilizes a single, lifespan-managed
httpx.AsyncClientpool, completely eliminating TCP/TLS handshaking overhead. - Fuzzy Matching & AI Resilience: Agent logic uses
rapidfuzz(Levenshtein distance) to mathematically map LLM hallucinations or typos to actual catalogitem_ids. - Prophet Anomaly Detection: Uses Interquartile Range (IQR) math to detect and strip out "panic buying" and "party spikes" before training the ML model, lowering false-positive restock alerts from ~25% to < 5%.
- Python 3.11+
- Node.js 18+
git clone https://github.com/kwakhare5/PreFill.git
cd PreFill
# Python virtual environment
python -m venv venv
.\venv\Scripts\activate
# Install backend dependencies
pip install -r requirements.txt# Run pytest test suite (16 tests must pass)
pytest backend/tests/ -v
# Start FastAPI backend
uvicorn backend.main:app --reloadcd frontend
# Install frontend dependencies
npm install
# Check production build
npm run build
# Start Next.js dev server
npm run devOpen http://localhost:3000 in your browser.
All data ingestion, model fitting, and profiling remain completely within the user-authorized account scope. Travel patterns, guest spikes, and dietary fluctuations are flagged locally to secure baseline forecasting and are never sold or utilized for third-party marketing purposes.
Made with ❤️ by Karan Wakhare