Feature Spec: Smart Automation Engine (Doc 05)

Product rules for safely normalizing manually entered, scanned, and imported grocery data before inventory changes.

1. User Goal

To ingest grocery data from external sources and populate the "Digital Twin" with 100% safety. The user should never have to question if the app "accidentally" combined two different items (like Cow Milk vs. Buffalo Milk).

2. Functional Logic & Rules

A. The Normalization Pipeline (Safety-First)

To protect users (allergies, dietary preferences), the app follows a Strict Match policy.

Extraction: Pull raw text (e.g., "Nandini Buffalo Milk 1L").
The "Exact Match" Rule: Items are only combined if the Category + Brand + Variant are identical. For example, "Cow Milk" and "Buffalo Milk" are treated as distinct entities, while "Whole Wheat Pasta" and "Durum Wheat Pasta" remain separate.
Pre-Built Taxonomy: The app includes a "Starter Pack" of common categories (Milk, Pasta, Flour, etc.). If a scanned item doesn’t fit a pre-built category, the user creates a new one once. This becomes part of that household’s custom taxonomy.

B. The "Ask Once" Confirmation (The Memory Rule)

New Item Discovery: The very first time "Brand X Sourdough" is scanned, the app triggers a "New Item" modal.
Fields to Confirm:
- Primary Category (select from pre-built list).
- Expiry Duration (e.g., "7 days after scan").
- Default Storage Location (e.g., "Fridge - Top Shelf").
Subsequent Scans: All future scans of "Brand X Sourdough" bypass these questions.

C. Quantity Management (Addition Logic)

Default: Add to Stock. (Current Inventory: 1 → Scan: 1 → Result: 2).
Manual Override: On the "Staging Area" screen, a simple [+] / [-] or [Replace] toggle is available for each item.

3. User Interface (The Workflow)

Screen 1: The Ingest Hub

Unified Entry: A single "plus" button that offers "Scan PDF" or "Camera Scan."
Progress Indicator: Real-time feedback while the OCR/Parser is working.

Screen 2: The Staging Area (Validation List)

This is the "Safety Buffer" where the user reviews what the app found. * Item Cards: Shows Name, Quantity, and the "Calculated Expiry." * Conflict Warning: If the app finds an item that is similar but not exact (e.g., scanning "Nandini Milk" when you already have "Heritage Milk"), it shows them as separate lines but highlights them to ask if the user wants to group them.

Screen 3: The "Photo-to-Date" Fallback

A "Quick-Camera" button inside the date field.
Captures a tiny image thumbnail of the expiry date on the packaging, which remains attached to the digital record for visual verification.

4. Edge Cases & Error Handling

Scenario	System Response
New Variant Found	If "Brand X Pasta" exists but "Brand X Fusilli Pasta" is scanned, the app treats it as a NEW item to avoid allergy/cooking time errors.
Illegible PDF/Receipt	If the line item cannot be parsed, the app presents a "Manual Entry" card with the raw text image displayed above it for easy typing.
Store Not Supported	If the receipt is not from Vijetha/Organic World, the app falls back to a "General OCR" which simply lists all found text for the user to tap and assign.

Scenario

System Response

New Variant Found

If "Brand X Pasta" exists but "Brand X Fusilli Pasta" is scanned, the app treats it as a NEW item to avoid allergy/cooking time errors.

Illegible PDF/Receipt

If the line item cannot be parsed, the app presents a "Manual Entry" card with the raw text image displayed above it for easy typing.

Store Not Supported

If the receipt is not from Vijetha/Organic World, the app falls back to a "General OCR" which simply lists all found text for the user to tap and assign.

5. Data Model (Requirements)

is_canonical: Boolean (Is this from the pre-built list?).
brand_name: String.
variant_details: String (e.g., "Whole Wheat", "Low Fat").
expiry_strategy: Enum (DaysFromScan, FixedDate, Manual).
location_id: Foreign Key (Link to the Almarah Cell).