How dadaloop82/evershelf works
1. Overall shape
EverShelf is a self-hosted pantry system built as a PHP + SQLite backend with a single-page web client served from the same repository. The web app, API, database, cron jobs, and runtime data all live on the same host, with optional Android add-ons for kiosk use and BLE scale support.
2. Browser/PWA frontend
index.html loads the app shell, and most UI logic sits in assets/js/app.js plus small core modules under assets/js/core/. The frontend is a mobile-first PWA with offline support, localStorage caching, a queued write model, and multilingual UI strings from translations/*.json.
3. API boundary
All server interactions go through api/index.php, which acts as the main router for action-based endpoints. Bootstrapping, environment loading, auth/security checks, logging, and database access are split into api/bootstrap.php, api/lib/*, api/logger.php, and api/database.php.
4. Persistence layer
Primary persistence is a SQLite database created and migrated by api/database.php inside data/. The data/ directory also stores runtime JSON caches and state files such as AI usage, shopping totals, dismissed anomalies, and backup timestamps. This means the backend is stateful but file-based, not service-based.
5. Core business domains
The backend is organized around a few main domains: products, inventory, shopping, settings, and dashboard/analytics. The API exposes operations such as barcode lookup, inventory add/use/list, Bring! list sync, smart shopping predictions, and server configuration reads/writes.
6. AI workflow
Gemini-powered features are server-side API calls, not browser-side logic. The API handles product identification, expiry extraction, recipe generation, anomaly explanations, shopping enrichment, and storage/shelf-life hints. Recipe generation streams results back with SSE, and the server keeps API keys hidden from the browser.
7. External integrations
The main external systems are Google Gemini, Bring!, Open Food Facts, and Home Assistant. Home Assistant integration is first-class through the API and OpenAPI contract, while Bring! and Open Food Facts support shopping sync and barcode enrichment. GitHub is also used for issue automation and release/update checks.
8. Background jobs and maintenance
api/cron_smart_shopping.php runs as a scheduled job to refresh predictions and trigger cleanup. Database maintenance includes automatic retention cleanup and VACUUM, with backup.sh providing local backups and optional Google Drive backup support described in the docs.
9. Offline and resilience model
The client is designed to keep working when disconnected: it caches server state locally, computes expiry stats from cached data, and queues mutations until connectivity returns. This creates a deliberate split between local optimistic UI state and authoritative server state in SQLite.
10. Security and operational boundaries
Configuration comes from .env, with optional API_TOKEN protection for all API calls and special handling for demo mode. Apache/Nginx rules, .htaccess, and Docker support reinforce the deployment boundary, while logging and encrypted GitHub issue tokens stay server-side.
11. Android kiosk add-on
evershelf-kiosk/ is a separate Android app that wraps the web UI in a locked-down WebView for tablet/kiosk deployments. It includes setup, settings, native TTS, update checks, and permissions for camera/mic use.
12. Integrated BLE scale gateway
The kiosk app also contains the BLE scale gateway: GatewayService, GatewayWebSocketServer, and BleScaleManager run a local foreground service that scans a Bluetooth scale and exposes readings over WebSocket. The web/server side has companion endpoints for discovery and relay, so the browser can receive scale events without mixed-content problems.
13. Deployment and automation
The repo is designed to ship via Docker Compose or a conventional PHP web server. GitHub Actions cover CI/security and Android builds, while docs/openapi.yaml and the wiki document the API and add-on behavior for operators and integrators.
14. How to draw the diagram
A clear diagram would center on the browser/PWA, the PHP API, and SQLite/data files, then show side links to Gemini, Bring!, Open Food Facts, and Home Assistant. Add two optional peripheral blocks: cron/backup jobs on the server side and the Android kiosk + BLE gateway on the client/add-on side.
Main entry points: index.php API router · app.js Frontend app · bootstrap.php Bootstrap · database.php SQLite layer
Components 25
Web client
Browser/PWA app and shared frontend assets.
- App shell · Single-page app entry point served from the repo root.
index.html - Frontend app · Main browser-side application logic.
assets/js/app.js - Core modules · Shared browser helpers for auth and DOM behavior.
assets/js/core/auth.js - Translations · Localized UI strings for the web client.
translations/en.json
PHP backend
API, persistence, cron jobs, and server-side integrations.
- API router · Main action-based endpoint dispatcher.
api/index.php - Bootstrap · Environment loading, auth setup, and request bootstrap.
api/bootstrap.php - Security · API token checks and request protection helpers.
api/lib/security.php - Env config · Loads runtime configuration from environment variables.
api/lib/env.php - SQLite layer · Database creation, migrations, and access to the local SQLite store.
api/database.php - Logging · Server-side logging and operational trace output.
api/logger.php - Runtime data · File-based caches and state alongside the database.
data/ai_usage.json - Products · Barcode lookup and product enrichment flows.
api/index.php - Inventory · Add, use, and list inventory state and expiry data.
api/index.php - Shopping · Shopping list sync, predictions, and related totals.
api/index.php - Settings · Server configuration reads and writes.
api/index.php - AI features · Server-side Gemini calls for identification, recipe generation, anomalies, and hints.
api/index.php
Android add-on
Kiosk app and BLE scale gateway.
- Kiosk app · Locked-down Android WebView wrapper for kiosk deployments.
evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/KioskActivity.kt - Scale gateway · BLE scale scanning and WebSocket relay service.
evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/scale/GatewayService.kt
Operations
Deployment, automation, docs, and maintenance scripts.
- Cron jobs · Scheduled refresh, cleanup, and shopping prediction maintenance.
api/cron_smart_shopping.php - Backups · Local backup and retention support.
backup.sh - API spec · OpenAPI definition for integrators and Home Assistant.
docs/openapi.yaml - Home Assistant · First-class external smart-home integration.
docs/wiki/Home-Assistant.md - Bring! · Shopping list synchronization provider.
scripts/sync-shopping-bring.php - Open Food Facts · Barcode and product enrichment source.
api/index.php - Gemini · External AI provider used by server-side workflows.
api/index.php
Connections 26
- App shell → Frontend app: loads · Bootstraps the web app shell into the browser.
- Frontend app → Core modules: uses · Shares auth and DOM helpers across the client.
- Frontend app → Translations: reads · Loads localized UI strings.
- Frontend app → API router: calls · Sends all server requests through the API router.
- API router → Bootstrap: boots · Initializes request handling and shared runtime state.
- Bootstrap → Env config: loads · Pulls runtime configuration from the environment.
- Bootstrap → Security: checks · Applies request authentication and protection.
- API router → SQLite layer: persists · Reads and writes SQLite-backed repository state.
- API router → Logging: logs · Emits operational and request logs.
- SQLite layer → Runtime data: stores · Maintains caches and runtime JSON state in data/.
- API router → Products: serves · Handles product lookup and enrichment actions.
- API router → Inventory: serves · Handles inventory mutation and listing actions.
- API router → Shopping: serves · Handles shopping synchronization and prediction actions.
- API router → Settings: serves · Exposes configuration reads and writes.
- API router → AI features: serves · Runs server-side AI workflows and streaming responses.
- Cron jobs → Shopping: refreshes · Recomputes smart shopping predictions and cleanup.
- Cron jobs → SQLite layer: maintains · Runs retention and VACUUM maintenance.
- Backups → Runtime data: backs up · Captures local runtime state and database-related files.
- Kiosk app → Frontend app: wraps · Displays the same web UI inside a locked-down Android shell.
- Scale gateway → API router: relays · Provides local scale discovery and relay support for the web app.
- Scale gateway → Kiosk app: feeds · Streams BLE scale readings into the kiosk runtime.
- API router → Open Food Facts: enriches · Uses product data from Open Food Facts.
- Shopping → Bring!: syncs · Syncs shopping lists with Bring!
- AI features → Gemini: calls · Uses Gemini for identification, recipes, anomalies, and hints.
- API router → Home Assistant: integrates · Exposes Home Assistant-facing operations and contract.
- API spec → API router: documents · Describes the API surface for operators and integrators.