What was decided, when, and why. Read this to understand the thinking behind the product — not just the output.
SA has specific market dynamics that create a defensible position: load-shedding affects refrigerated stock decisions, WhatsApp is the dominant communication layer, Woolies/Checkers/Makro are the key store relationships, and POPIA creates a data compliance requirement. Building globally-generic would miss all of these. A locally-specific product is harder to clone.
Checkers Sixty60 and Woolies Dash integrations are first-class requirements (not nice-to-haves). WhatsApp bot for Grace/Thabo is in Phase 2 core, not an afterthought. Load-shedding is a first-class event in the IoT sensor architecture for Pantry Pro.
User research (Patrick, Melisa) consistently pushed beyond grocery into bills, family coordination, home maintenance, and domestic worker management. The entry point is grocery because it's the highest-frequency use case, but the product ceiling is a unified household layer. Grocery-only would have been a feature, not a product.
All Phase 2 scope (bills, smart home, family coordination, school groups) is now in-scope. Competitive positioning shifts from "grocery app" to "household OS" — different competitors, different pricing, different retention dynamics. Grace (domestic worker) becomes a critical Phase 2 persona.
The restaurant owner persona (Sipho) emerged from thinking about power users with sensors. The underlying tech — inventory engine, OCR capture, RLS, sensor layer — is identical between households and restaurants. The differentiator is scale, staff roles, and commercial features (supplier management, food cost %). Building two separate products would waste 80% of the work.
Architecture decisions need to accommodate both tiers from the start (already done — baseline_stock table, multi-user RLS, sensor layer all work for both). Monetization model: household = freemium, Pro = paid B2B tier. This is the commercial wedge that could fund household growth.
Every manual-entry pantry app has a graveyard of abandoned accounts. The insight from Melissa's hardware setup confirms it: once sensors automate stock tracking, she never has to think about it. The same principle applies to receipt scanning — photograph the receipt, app does the rest. Human effort = churn risk.
Receipt scanning (Sprint 3) and barcode scan are P0, not P1. Email order parsing (Sixty60, Woolies Dash) is Sprint 5. IoT sensor layer is Phase 2. The onboarding flow (currently missing) must make the first passive capture feel magical or users will not return.
Freemium for households (basic inventory + capture free, full OS paid). Pantry Pro as a paid B2B tier (restaurant). In-app grocery ordering as a transaction revenue layer long-term. None of this has been validated. Willingness to pay has not been tested with any tester.
Define pricing tiers before Sprint 6. Test willingness to pay with existing testers. Decide whether to build the waitlist before or after the monetization model is clear. The Pro tier (Sipho) likely has a shorter path to revenue than household freemium.
Grace (domestic worker) cannot be expected to use a smartphone app. Thabo shops in-store with poor signal. Lerato's hands are full in the kitchen. The product must work across surfaces — voice for kitchen/domestic, WhatsApp for in-store, web for planning. Web first is pragmatic; voice-first is a design constraint on all decisions.
Every feature must have a voice/conversational equivalent planned, even if not built yet. WhatsApp bot in Phase 2 is not optional — it's the Grace and Thabo access layer. Nest Hub integration (MEL-003) is for Sipho's restaurant floor and Lerato's kitchen.
Melissa's hardware stack (Pi 5, Home Assistant, D1 Mini, Zigbee sensors) is fully working. For households, sensor automation is a power-user feature — most households won't have hardware. For restaurants (Sipho), sensors are the core value proposition: you cannot run a kitchen without real-time stock and temperature visibility.
Architecture already has the IoT layer designed (MQTT → Pi Hub → Supabase Realtime). PRO-009/010/011/012 (sensor stories) are in the Pantry Pro epic. The webhook receiver and Realtime infrastructure need to be built before Pro launch — but these components are already in the architecture design.
Melissa's exact words: "Automate what you can. The rest is left to human intervention." This is the right product philosophy for household management. Automatic receipt scanning, automatic low-stock detection, automatic purchase order drafts — but all require one-tap human confirmation before acting. Trust is built through transparency and control.
Every automation flow has an "approve / dismiss" step (see PRO-011 sensor-triggered PO). Receipt OCR results are shown for confirmation before committing to inventory. Shopping list auto-generation from recipes requires review. This is not optional — removing the approval step would erode trust and cause data quality issues.
A new Lerato lands on the app after signing up. There are no items in her inventory, no household members added, no budget set. Nothing. The empty state experience is not designed. She has no guided path to her first value moment. This is where most consumer apps lose users forever.
Design an onboarding flow that gets Lerato to her first receipt scan within 3 minutes of signing up. Define: what does "value" mean for a first-time user? Scan a receipt? Set up the household? Add first items? The answer to this question shapes the entire onboarding design.
Row Level Security (RLS) was the deciding factor — POPIA requires per-household data isolation, and RLS enforces this at the database layer without application-level code. Realtime is needed for the Sprint 5 dashboard and Pantry Pro live sensor view. Edge Functions handle the Google Cloud Vision OCR integration. Managed auth removes a security risk.
All database operations go through Supabase's PostgREST API or Edge Functions. Realtime via websockets is available without additional infrastructure. The sensor pipeline (IoT → Pi Hub → Supabase Realtime → React dashboard) is already architecturally supported. Project ID: osmtvniihyxpkadjvyur.
Cloudflare Pages offers global edge deployment at low cost, with automatic SSL and branch previews. For SA users, edge nodes in Johannesburg reduce latency. The free tier covers the current traffic volume. No server management required.
App lives at pantry-app.tapfumamv.com. Reports hub at pantry-reports.tapfumamv.com. Spike at pantry-spike.pages.dev. All static deploys — no server to manage. If WhatsApp bot (Phase 2) requires server-side routing, a Cloudflare Worker is the natural extension.
On-device OCR (Tesseract, Apple Vision Framework) was considered but rejected: SA receipts have varied layouts, thermal printing quality varies, and on-device models struggle with non-English product names. Google Cloud Vision handles this reliably. The cost at current scale is negligible.
Receipt scanning requires an internet connection (no offline mode for capture). At scale, GCV costs need monitoring. The Edge Function architecture means the API key is never exposed to the client. Supplier invoice scanning (PRO-008) reuses this same Edge Function with a different parser.