HomeStock: Instructions file for Claude Code

HomeStock

Automatic household inventory system. Builds a live picture of what a household owns (groceries, toiletries, household goods) by parsing receipts from grocery deliveries and online orders — not manual entry. Predicts when items run low or expire, supports multiple homes/locations per user, and powers downstream features like recipe suggestions and auto-reordering.

Full product spec: PRD-Home-Stock-Room.md — read it before making product/architecture decisions.

Status

Pre-code. The repo currently contains only the PRD (Draft v0.1). No stack, no scaffolding, no build tooling chosen yet.

Core concepts

• Ingestion — two input paths that normalize to a common event schema:
  • Email: OAuth (Gmail/IMAP), read-only, filtered to known retailer sender domains, per-retailer HTML parsing templates.
  • Manual upload: photo (OCR) or PDF, same normalization pipeline as email.
• Item resolution — fuzzy-match raw receipt strings (e.g. TESCO WHL CHKN 1.2KG) to a canonical product table. Unmatched items trigger a one-time user confirmation that is then learned per retailer.
• Multi-home data model — household_id → many location_id (e.g. Home A – Fridge, Home A – Pantry). Inventory state keyed by (location_id, item_id, estimated_qty, last_updated).
• Prediction (two distinct models):
  • Behavioral reorder model for non-perishables (order-cadence forecasting).
  • Shelf-life/spoilage model for perishables (rules-based, adjusted by storage location).
• Downstream — recipe suggester (near-expiry weighted) and reorder/basket pre-fill (stretch).

Common ingestion event schema:

{ household_id, location_id, item_raw_name, item_canonical_id,
  quantity, unit, price, date, source /* "email" | "upload" */ }

MVP scope (v1)

In: email parsing for 2–3 retailers (start Tesco + Amazon), manual upload + OCR, single-location inventory view, basic non-perishable reorder prediction, basic perishable expiry flagging (static shelf-life table).