# ๐ EverShelf
> **Self-hosted pantry management system** โ Track your food inventory, scan barcodes, get AI-powered recipe suggestions, and reduce waste.
๐ **Website:** [evershelfproject.dadaloop.it](https://evershelfproject.dadaloop.it/)
[](LICENSE)
[](https://www.php.net/)
[](https://www.sqlite.org/)
[](Dockerfile)
[](translations/)
---
## ๐ Recent Updates
- **3 new AI features (Gemini)** โ Storage/shelf-life hint shown inline in the add form; AI-enriched shopping suggestions with a short practical tip per item; plain-language anomaly explanation via a "๐ค Spiega" button on anomaly banners.
- **Security hardening** โ `get_settings` no longer exposes API keys in plain text (boolean flags only); `save_settings` protected by optional `SETTINGS_TOKEN` (validated with `hash_equals`); native `DEMO_MODE` in `.env` blocks all write operations at the PHP router level before any other guard.
- **Real-time webapp update detection** โ An inline header pill appears when a newer release is on GitHub (checked on load + every 30 min); no intrusive full-page banners.
- **Gemini availability flag** โ All AI entry points check `_geminiAvailable` before firing; the header button shows a visual no-AI state (greyed + amber dot) when no key is configured.
- **Dashboard skeleton loading** โ Stat cards show an animated shimmer while data loads instead of a jarring `0` flash for 3โ5 seconds.
- **APK self-update with conflict recovery** โ Both Kiosk (v1.4.0) and Scale Gateway (v2.1.0) use the `PackageInstaller` session API for OTA installs; a signature conflict now shows a dialog to uninstall the old version instead of a cryptic failure.
- **Smarter low-quantity alerts** โ The "suspiciously low quantity" banner is no longer raised for a partially-used entry when the same product has stock in another location. Sibling entries are detected by barcode or name+brand.
- **Non-alarmist expired banner** โ Adapts icon, colour, and title to the actual safety level: green โ
for long-life products still safe, amber ๐ for items to check, red ๐ซ only for genuinely dangerous items.
- Recipe and meal-plan labels now resolve at runtime from translations, preventing raw placeholders from appearing in the UI.
- Recipe generation now receives the selected app language and enforces localized output in both streaming and non-streaming API flows.
## โจ Features
### ๐ฆ Inventory Management
- **Barcode scanning** โ Scan products with your phone camera using QuaggaJS
- **AI identification** โ Take a photo and let Google Gemini identify the product, with suggestions from your existing inventory; gracefully shows a friendly message when AI quota is exhausted instead of a raw API error
- **Smart locations** โ Track items across Pantry, Fridge, Freezer, and custom locations
- **Expiry tracking** โ Automatic shelf-life estimation based on product type and storage
- **Opened product tracking** โ Reduced shelf-life calculation when packages are opened; opened-product expiry is now also checked when building banner alerts (not just the dashboard section)
- **Vacuum-sealed support** โ Extended expiry dates for vacuum-sealed items
- **Anomaly detection** โ Banner alerts for suspicious quantities and consumption predictions with inline correction; dismiss button now shows the current inventory quantity so the action is unambiguous ("La quantitร รจ giusta (2 pz)")
### ๐ค AI-Powered (Google Gemini)
- **Expiry date reading** โ Photograph a label and extract the expiry date automatically
- **Product identification** โ Point your camera at any product for instant recognition
- **Existing product matching** โ AI scan shows matching products already in your pantry before suggesting new ones
- **Storage & shelf-life hint** โ When adding a new product, Gemini suggests the optimal storage location and shelf-life in the background; shown as an inline AI badge next to the expiry estimate
- **Recipe generation** โ Get personalized recipes based on what's in your pantry; streams live via Server-Sent Events so results appear as they are generated
- **Smart chat assistant** โ Ask questions about your inventory, get cooking tips
- **Shopping suggestions with tips** โ AI-powered purchase recommendations, each enriched with a short practical buying/storing tip
- **Anomaly explanation** โ "๐ค Spiega" button on anomaly banners explains in plain language why a discrepancy likely occurred and what to do
- **Model fallback** โ All AI endpoints try `gemini-2.5-flash` first and fall back to `gemini-2.0-flash` automatically
- **Graceful no-key state** โ When no Gemini key is configured, AI entry points show a friendly message; the header button is visually greyed with an amber dot
### ๐ Shopping List
- **Bring! integration** โ Sync with the [Bring!](https://www.getbring.com/) shopping list app
- **Generic shopping names** โ Products are grouped by type ("Latte", "Affettato", "Panna da cucina") rather than brand, keeping the Bring! list clean and consolidated
- **Smart predictions** โ Know what you'll need before you run out
- **Auto-add on depletion** โ When a product reaches zero the app adds it to Bring! automatically, no confirmation needed
- **Auto-remove on scan** โ Products are removed from the shopping list when scanned in - **Auto-migration** โ Items already on the Bring! list are silently renamed to their generic name in the background (throttled, runs on list load)
- **Catalog coverage** โ All product types resolve to a German Bring! catalog key for icon and category display in the Bring! app
### ๐ณ Cooking Mode
- **Step-by-step guidance** โ Follow recipes with a hands-free cooking interface
- **Text-to-Speech** โ Voice readout of recipe steps; supports browser Web Speech API, native Android TTS (kiosk), or a custom REST endpoint (Home Assistant, etc.); retries voice loading for up to 10 seconds with a fallback refresh button; TTS activates automatically without requiring the global TTS setting to be enabled
- **Auto-read on navigate** โ Each step is read aloud automatically when you tap Next or Previous; the first step is read when entering cooking mode
- **Timer voice alerts** โ 10-second countdown warning spoken aloud before each timer expires; expiry announced vocally when time is up
- **Recipe completion** โ "Buon appetito!" spoken when the last step is confirmed
- **Built-in timer** โ Automatic timer suggestions based on recipe instructions
- **Ingredient tracking** โ Mark ingredients as used during cooking; leftover quantities prompt a "move to another location" flow
### ๐ Dashboard
- **Waste tracking** โ Monitor consumed vs. wasted products over 30 days
- **Anti-waste report** โ Personalised waste rate vs. national average with annual kg estimate; shown above the expiring-items list
- **Expiry alerts** โ Visual warnings for expired and soon-to-expire items
- **Opened products panel** โ Tracks partially-used items; expiry is recalculated from the opening date using AI (Gemini) + per-category rule fallback; whole sealed packages always keep their original manufacturer expiry; conf items with mixed whole + fractional units are shown as two separate entries
- **Freezer shelf-life** โ Granular per-product estimates (USDA/EFSA): fish 120 d, poultry 270 d, whole red-meat cuts 365 d, mince 120 d, vegetables/fruit 270 d, generic 180 d; AI + cache still take priority over rules
- **Safety ratings** โ Smart assessment of expired product safety (by category and location); expired unsafe items shown with a red danger banner and "L'ho buttato" as the primary action
- **Expired product banner** โ Products that have passed their effective shelf-life (including opened-product reduced expiry) appear in the top notification banner; icon, colour and title adapt to the actual safety level (โ
green for safe, ๐ amber to check, ๐ซ red for danger); high-risk items get a prominent discard action
- **Quick recipe bar** โ One-tap recipe suggestion using expiring products
- **Anomaly banner** โ Scrollable banner with suspicious quantities and consumption prediction mismatches, with one-tap correction or inline edit
- **Expired/expiring alerts** โ Priority-sorted banner notifications for expired and soon-to-expire products with use, throw, edit, and dismiss actions
- **Swipe navigation** โ Touch swipe or tap arrows/dots to browse banner notifications
- **Quick-access buttons** โ Recently used and most popular products shown on the inventory page for fast access
### ๐ฑ Progressive Web App
- **Mobile-first design** โ Optimized for phones, works on tablets and desktop
- **Installable** โ Add to home screen for a native app experience
- **Multi-device** โ Settings and data sync across devices on the same server
### โ๏ธ Smart Scale Integration (Add-on)
- **Bluetooth gateway** โ Connects a BLE smart scale to EverShelf via local WebSocket
- **SSE relay** โ Server-side relay avoids mixed-content (HTTPSโWS) issues
- **Auto-discovery** โ Server scans LAN to find the gateway automatically
- **Auto weight reading** โ When adding/using a product with unit g/ml, weight fills automatically
- **10g threshold** โ Ignores readings that haven't changed enough between products - **Duplicate-reading prevention** โ Server-side 12-second dedup window rejects a second scale-triggered deduction of the same product, guarding against BLE multi-fire- **ml conversion hint** โ Shows "weight in grams โ will be converted to ml" when product unit is ml
- **Stability + auto-confirm** โ 10s stable wait + 5s countdown before confirming
- **Real-time status** โ Scale connection indicator always visible in the header
- **Multi-protocol** โ Supports Bluetooth SIG Weight Scale, Body Composition, Xiaomi Mi Scale 2 and 100+ models
- **Android gateway app** โ [`evershelf-scale-gateway/`](evershelf-scale-gateway/) โ open-source, downloadable APK
### ๐บ Android Kiosk Mode (Add-on)
- **Dedicated tablet app** โ Full-screen WebView wrapper for wall-mounted kitchen tablets
- **True kiosk lock** โ Screen pinning blocks home/recent buttons
- **Setup wizard** โ 3-step guided configuration (URL, connection test, gateway)
- **Gateway auto-launch** โ Launches the Scale Gateway in the background on startup
- **Camera & mic permissions** โ Full hardware access for barcode scanning and voice
- **Native TTS bridge** โ Cooking mode voice readout uses the Android TextToSpeech engine directly, bypassing Web Speech API voice limitations; no offline voice packs required
- **Hard refresh** โ โป button clears WebView cache to pick up web app updates
- **Update notifications** โ Checks GitHub releases every 6h, shows banner when updates available
- **SSL support** โ Accepts self-signed certificates
- **Android kiosk app** โ [`evershelf-kiosk/`](evershelf-kiosk/) โ downloadable APK
---
## ๐ Quick Start
### Prerequisites
- **Web server** with PHP 8.0+ (Apache or Nginx)
- **PHP extensions**: `pdo_sqlite`, `curl`, `mbstring`, `json`
- **HTTPS** recommended (required for camera access on mobile)
### Installation
#### Option A: Docker (recommended)
```bash
# 1. Clone the repository
git clone https://github.com/dadaloop82/EverShelf.git
cd EverShelf
# 2. Create configuration file
cp .env.example .env
nano .env
# 3. Start with Docker Compose
docker compose up -d
# โ Open http://localhost:8080
```
#### Option B: Manual
```bash
# 1. Clone the repository
git clone https://github.com/dadaloop82/EverShelf.git
cd EverShelf
# 2. Create configuration file
cp .env.example .env
# 3. Set permissions
chmod 755 data/
chmod 664 data/.gitkeep
chown -R www-data:www-data data/
# 4. Edit your configuration
nano .env
```
### Configuration (.env)
```ini
# Required for AI features (get a key at https://aistudio.google.com/app/apikey)
GEMINI_API_KEY=your_api_key_here
# Optional: Bring! shopping list integration
BRING_EMAIL=your_email@example.com
BRING_PASSWORD=your_password
# Optional: Text-to-Speech for cooking mode
TTS_URL=http://your-home-assistant:8123/api/events/tts_speak
TTS_TOKEN=your_long_lived_token
TTS_ENABLED=true
# Optional: Security โ protect the save_settings endpoint
# Set a strong random string; the Settings UI will ask for it before saving
SETTINGS_TOKEN=
# Optional: Demo mode โ block all write operations at the router level
DEMO_MODE=false
```
### Web Server Configuration
Apache (.htaccess)
The app works out of the box with Apache if placed in the web root or a subdirectory. Make sure `mod_rewrite` is enabled and `AllowOverride All` is set.
```apache
AllowOverride All
Require all granted
```
Nginx
```nginx
server {
listen 80;
server_name your-server.local;
root /var/www/html/evershelf;
index index.html;
location /api/ {
try_files $uri $uri/ =404;
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
# Deny access to sensitive files
location ~ /\.env { deny all; }
location ~ /data/ { deny all; }
location ~ /backup\.sh { deny all; }
}
```
### HTTPS Setup (Recommended)
Camera access requires HTTPS on most mobile browsers. Options:
- **Let's Encrypt** with Certbot (for public-facing servers)
- **Self-signed certificate** (for local network only)
- **Reverse proxy** (e.g., Caddy, Traefik) with automatic TLS
### Cron Job (Optional)
Set up a cron job for smart shopping predictions:
```bash
# Run every 5 minutes
*/5 * * * * php /path/to/evershelf/api/cron_smart_shopping.php >> /path/to/evershelf/data/cron.log 2>&1
```
### Backup (Optional)
The included `backup.sh` creates local daily backups of your database:
```bash
# Run daily at 3 AM
0 3 * * * /path/to/evershelf/backup.sh
```
---
## ๐๏ธ Architecture
```
evershelf/
โโโ index.html # Single-page application (SPA)
โโโ manifest.json # PWA manifest
โโโ .env.example # Configuration template
โโโ backup.sh # Local database backup script
โโโ LICENSE # MIT License
โ
โโโ api/
โ โโโ index.php # Main API router (all endpoints)
โ โโโ database.php # SQLite schema, migrations, helpers
โ โโโ cron_smart_shopping.php # Background job for predictions
โ
โโโ assets/
โ โโโ css/style.css # All application styles
โ โโโ js/app.js # All application logic
โ โโโ img/ # Static images
โ
โโโ data/ # Runtime data (gitignored)
โโโ evershelf.db # SQLite database (auto-created)
โโโ backups/ # Local DB backups
โโโ *.json # Token/cache files
evershelf-scale-gateway/ # โ๏ธ Android BLE gateway (add-on)
โโโ README.md # Setup & protocol docs
โโโ app/src/ # Kotlin Android source (WebSocket + BLE)
evershelf-kiosk/ # ๐บ Android kiosk app (add-on)
โโโ README.md # Setup & feature docs
โโโ app/src/ # Kotlin Android source (WebView wrapper)
```
### API Endpoints
| Category | Action | Method | Description |
|----------|--------|--------|-------------|
| **Products** | `search_barcode` | GET | Find product by barcode |
| | `lookup_barcode` | GET | Look up barcode on Open Food Facts |
| | `product_save` | POST | Create or update a product |
| | `products_list` | GET | List all products |
| **Inventory** | `inventory_list` | GET | List inventory items |
| | `inventory_add` | POST | Add product to inventory |
| | `inventory_use` | POST | Use/consume from inventory |
| | `inventory_summary` | GET | Count by location |
| **AI** | `gemini_identify` | POST | Identify product from photo |
| | `gemini_expiry` | POST | Read expiry date from photo |
| | `gemini_chat` | POST | Chat with AI assistant |
| | `generate_recipe` | POST | Generate recipe from inventory |
| | `gemini_product_hint` | POST | Storage location + shelf-life hint |
| | `gemini_shopping_enrich` | POST | Enrich shopping suggestions with tips |
| | `gemini_anomaly_explain` | POST | Plain-language anomaly explanation |
| **Shopping** | `bring_list` | GET | Get Bring! shopping list |
| | `bring_add` | POST | Add items to Bring! |
| | `smart_shopping` | GET | Smart shopping predictions |
| **Settings** | `get_settings` | GET | Get server configuration |
| | `save_settings` | POST | Update server configuration |
---
## ๐ Security Notes
- **Credentials** are stored in `.env` (server-side, never committed to Git)
- **Database** stays local โ never pushed to remote repositories
- **API keys are never exposed to the browser** โ `get_settings` returns only boolean flags (`gemini_key_set`, `settings_token_set`), never raw key values
- **Settings write protection** โ set `SETTINGS_TOKEN` in `.env` to require a secret token (`X-Settings-Token` header) for all `save_settings` calls; validated with `hash_equals` to prevent timing attacks
- **Demo / public mode** โ set `DEMO_MODE=true` to block all write operations at the PHP router level before any business logic runs
- The API uses **parameterized SQL queries** (PDO prepared statements) against injection
- **Input validation** on all inventory operations (quantity bounds, location whitelist)
- Consider adding **reverse-proxy authentication** (e.g. Authelia, Nginx `auth_basic`) if the server is accessible from the internet
---
## ๐ ๏ธ Development
```bash
# Run PHP's built-in server for local development
php -S localhost:8080 -t /path/to/evershelf
# Check PHP syntax
php -l api/index.php
php -l api/database.php
```
The application uses no build tools โ edit files directly and refresh.
---
## ๐ Roadmap
- [x] Multi-language support (i18n) โ 3 languages (it/en/de), 347 keys
- [ ] User authentication / multi-user support
- [x] Docker container for easy deployment โ see [Dockerfile](Dockerfile) + [docker-compose.yml](docker-compose.yml)
- [x] REST API documentation (OpenAPI/Swagger) โ see [docs/openapi.yaml](docs/openapi.yaml)
- [x] First-run setup wizard โ 4-step guided configuration
- [x] API rate limiting โ file-based, 3 tiers (120/15/5 req/min)
- [x] CI/CD pipeline โ GitHub Actions (lint, Docker build, translation validation)
- [x] Android kiosk mode โ dedicated tablet app with screen pinning
- [x] Anomaly detection banner โ suspicious quantities + consumption predictions
- [x] AI scan local matching โ suggest existing pantry products before OFF lookup
- [x] Scale auto-fill improvements โ 10g threshold, ml conversion hints
- [x] Update notification system โ inline header pill (webapp) + kiosk checks GitHub releases
- [x] Generic shopping name grouping โ compound-phrase + keyword map (100+ entries) + Gemini AI fallback
- [x] Auto-add to Bring! on product depletion โ no confirmation step when stock reaches zero
- [x] Native Android TTS in kiosk โ bypasses Web Speech API voice detection issues
- [x] AI product storage hint โ background Gemini call suggests location + shelf-life in the add form
- [x] AI shopping tips enrichment โ each suggestion enriched with a short practical tip
- [x] AI anomaly explanation โ "๐ค Spiega" button explains discrepancies in plain language
- [x] Security hardening โ no raw key exposure, SETTINGS_TOKEN auth, DEMO_MODE native blocking
- [ ] Offline mode with service worker
- [ ] Export/import inventory data
- [ ] Notification system (Telegram, email) for expiring products
---
## ๐ Translations
The app supports multiple languages via JSON translation files in the `translations/` folder.
| Language | Status |
|----------|--------|
| ๐ฎ๐น Italian (it) | โ
Complete (base) |
| ๐ฌ๐ง English (en) | โ
Complete |
| ๐ฉ๐ช German (de) | โ
Complete |
**Want to add your language?** See the [Translation Guide](CONTRIBUTING.md#-adding-translations) โ just copy `translations/it.json`, translate the values, and submit a PR!
---
## ๐ค Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -m 'Add my feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request
---
## ๐ License
This project is licensed under the **MIT License** โ see the [LICENSE](LICENSE) file for details.
---
## ๐จโ๐ป Author
**Stimpfl Daniel** โ [evershelfproject@gmail.com](mailto:evershelfproject@gmail.com)
- Website: [evershelfproject.dadaloop.it](https://evershelfproject.dadaloop.it/)
- GitHub: [@dadaloop82](https://github.com/dadaloop82)
---
## ๐ธ Screenshots
| | | |
|:---:|:---:|:---:|
|  |  |  |
| **Dashboard** โ Inventory overview with counters by location (pantry, fridge, freezer), upcoming expiry alerts, and consumed vs. wasted tracking over the last 30 days. | **Inventory** โ Full product list filterable by location (All / Pantry / Fridge / Freezer) and searchable by name, with category, quantity, and expiry date. | **Barcode Scanner** โ Scan barcodes with the camera (QuaggaJS) or enter manually. Shopping mode lets you register purchased products in quick sequence. |
|  |  |  |
| **AI Recipe Detail** โ Recipe generated by Gemini AI using expiring ingredients: each ingredient is matched to the real inventory with quantity and location, ready to scale. | **Recipes** โ History of AI-generated recipes, organized by day and meal (lunch / dinner / other), with preparation and cooking time. | **Cooking Mode** โ Fullscreen step-by-step guide with Text-to-Speech. Each step shows the ingredient to use from your pantry with an integrated "Use" button. |
|  |  |  |
| **Gemini Chat** โ AI assistant that knows your pantry, your appliances, and your preferences. Suggests snacks, smoothies, or quick meals with a single tap. | **Shopping List** โ List synced with Bring!, organized by product category, with urgency indicators and links to search for prices online. | **Smart Predictions** โ AI analysis of historical consumption: shows what is running low, how much time is left, and why restocking is recommended (regular use, nearly empty, opened). |