# ✨ Features

A complete walkthrough of EverShelf's features.

---

## 📦 Inventory Management

### Adding Products

- Tap **➕** to open the add form
- Search by name or scan a barcode
- Select storage location: Pantry, Fridge, Freezer, or a custom location
- Enter quantity and expiry date (or let AI estimate it)
- Mark as vacuum-sealed or opened for adjusted shelf-life calculation

### Barcode Scanning

Tap the barcode icon to open the camera scanner (QuaggaJS). The app:
1. Checks your local database first
2. Falls back to [Open Food Facts](https://world.openfoodfacts.org/) for unknown barcodes
3. Pre-fills the product form with name, brand, category

### AI Product Identification

Point the camera at any product — Gemini identifies it and:
- Shows matching products **already in your pantry** first
- Suggests a new product entry with pre-filled fields
- Provides a storage location hint and estimated shelf-life

### Storage Locations

| Location | Icon | Notes |
|----------|------|-------|
| Pantry | 🏠 | Room temperature |
| Fridge | ❄️ | Refrigerated |
| Freezer | 🧊 | Frozen |
| Custom | 📦 | Any name you choose |

### Opened Product Tracking

When you partially use a product and mark it as "opened":
- Shelf-life is recalculated from the opening date
- Uses AI (Gemini) + per-category rules (e.g. fish: 2 days, milk: 3 days)
- Whole sealed packages always keep their original manufacturer expiry
- Products with mixed whole + fractional units show as two separate entries

### Vacuum-Sealed Support

Mark any product as vacuum-sealed to extend its estimated expiry date (typically 2–3× the normal shelf-life).

---

## 🤖 AI Features (Google Gemini)

All AI features require a `GEMINI_API_KEY` in `.env`. They degrade gracefully when the key is missing or quota is exceeded.

### Expiry Date Reading

Photograph the label on a product — Gemini extracts the expiry date and fills the field automatically.

### Product Identification

Camera-based identification with pantry matching. See [Adding Products](#adding-products) above.

### Storage & Shelf-life Hint

When adding a new product, a background Gemini call suggests:
- Optimal storage location
- Estimated shelf-life in days

Shown as an inline AI badge next to the expiry estimate. Does not block the form.

### Recipe Generation

Tap **🍳 Recipes** → **Generate Recipe** to get a recipe using:
- Ingredients about to expire (prioritised)
- What's currently in your pantry
- Your language preference

Recipes stream live via Server-Sent Events so results appear as they are generated.

### AI Chat Assistant

Open **💬 Chat** to ask questions like:
- "What can I make with eggs and pasta?"
- "How long does cooked ham last once opened in the fridge?"
- "Suggest a quick snack"

The assistant knows your current inventory.

### Shopping Suggestions with Tips

Smart shopping predictions include a short AI-generated practical tip per item (e.g. "Buy the 2 kg bag — it freezes well").

### Anomaly Explanation

When the dashboard shows a suspicious quantity banner, tap **🤖 Spiega** to get a plain-language explanation of why the discrepancy likely occurred and what to do about it.

### Model Fallback

All AI endpoints try `gemini-2.5-flash` first and automatically fall back to `gemini-2.0-flash` if unavailable.

---

## 🛒 Shopping List (Bring! Integration)

Configure `BRING_EMAIL` and `BRING_PASSWORD` in `.env` to enable.

### Features

- **View and manage** your Bring! list inside EverShelf
- **Auto-add on depletion** — when stock hits zero, the product is added to Bring! automatically
- **Auto-remove on scan** — scanning a product in removes it from the shopping list
- **Generic names** — products are grouped by type ("Latte", "Panna da cucina") not brand, keeping the list clean
- **Auto-migration** — items already on Bring! are silently renamed to their generic name on list load
- **Catalog coverage** — 100+ product types mapped to Bring! catalog keys for icons and categories in the Bring! app
- **AI fallback** — unknown product types use Gemini to determine the best generic name

---

## 🍳 Cooking Mode

Start cooking mode from any recipe by tapping **▶ Start Cooking**.

### Features

- **Step-by-step guidance** — fullscreen, distraction-free interface
- **Text-to-Speech** — each step is read aloud automatically when you navigate; supports:
  - Browser Web Speech API (default)
  - Native Android TTS (kiosk app)
  - Custom REST endpoint (e.g. Home Assistant)
- **Built-in timers** — automatic timer suggestions based on recipe text; 10-second vocal countdown warning before expiry
- **Ingredient tracking** — mark ingredients as used; leftover quantities prompt a "move to another location" flow
- **Recipe completion** — "Buon appetito!" *(Enjoy your meal!)* spoken on the last step

---

## 📊 Dashboard

### Inventory Overview

Three stat cards at the top show item counts for Pantry, Fridge, and Freezer with animated skeleton loading while data fetches.

### Expiry Alerts Banner

Priority-sorted notifications for:
- Expired products (with safety assessment — green ✅ safe, amber 👀 check, red 🚫 danger)
- Products expiring within 3 days

Actions per item: Use, Throw away, Edit, Dismiss. Swipe or tap arrows to navigate.

### Anomaly Banner

Highlights suspicious quantities (e.g. "You have 0 eggs but used 12 this month"). Actions:
- One-tap correction to the suggested quantity
- Inline edit with free-form quantity
- "🤖 Explain" for AI explanation
- Dismiss (with current quantity shown: "The quantity is correct (2 pcs)")

### Anti-Waste Report

Shows your waste rate vs. the national average with an estimated annual kg of food wasted.

### Quick Recipe Bar

One-tap recipe suggestion using the ingredients closest to expiry.

---

## 📱 Progressive Web App (PWA)

EverShelf is installable as a PWA on any device:

1. Open in Chrome/Safari/Edge
2. Tap **"Add to Home Screen"** (browser menu)
3. Launch from the home screen like a native app

Features:
- Offline-capable shell (assets cached)
- Full-screen mode on mobile
- Multi-device: all data syncs via the shared server

---

## 🔔 Update Notifications

When a new EverShelf release is published on GitHub, a small pill appears in the header. Click it to see the changelog. Checked on load and every 30 minutes.

---

## 🌍 Multi-language

The app auto-detects your browser language. Supported: 🇮🇹 Italian, 🇬🇧 English, 🇩🇪 German.

Change the language in **Settings → Language**.

See [Translations](Translations) to add a new language.

---

## ↩ Transaction History & Undo

**Settings → Storico** shows all inventory operations (adds, uses, throws).

- Any operation within the **last 24 hours** shows a red ↩ undo button
- Tapping ↩ shows a 5-second countdown confirmation before reversing the transaction
- The original stock is restored and a counter-transaction is logged

---

## 🔒 Security Features

- API keys never exposed to the browser (`get_settings` returns boolean flags only)
- `save_settings` protected by optional `SETTINGS_TOKEN` (validated with `hash_equals`)
- `DEMO_MODE=true` blocks all write operations at the PHP router level
- Parameterized SQL queries (PDO prepared statements) throughout
- Input validation on all inventory operations (quantity bounds, location whitelist)
- See [Configuration](Configuration) for details