Grocy

Grocy is a self‑hosted, web‑based ERP system focused on household resource planning. From a developer’s standpoint it is a lightweight PHP application that exposes a rich REST‑like API, enabling integration with mobile apps, smart home devices, or custom dashboards. The core business logic is written in modern PHP 8.x, leveraging Composer for dependency management and Yarn for front‑end assets. The application is deliberately minimalistic—no heavyweight frameworks—to keep the codebase approachable while still offering a full feature set for grocery, pantry, and household inventory management.

Key Features

• Inventory & Stock Management – CRUD operations for products, batches, and storage locations; support for expiry dates, quantity units, and minimum stock thresholds.
• Shopping & Recipe Automation – Automatic shopping list generation based on recipes and current stock; intelligent “due score” calculations to prioritize items.
• Barcode Integration – Web‑camera or external barcode scanners can trigger product lookups via the built‑in Open Food Facts integration, and any additional services can be added through a plugin system.
• API & Webhooks – A comprehensive JSON‑based API exposes all CRUD endpoints; developers can hook into events (e.g., product added, batch expiring) via configurable webhooks or an internal event bus.

Technical Stack

The application follows a conventional MVC pattern but eschews heavy frameworks like Laravel in favor of hand‑rolled routing and service containers. This design choice keeps the binary size small (≈ 50 MB for Docker) and speeds up deployment while still allowing developers to inject custom services or override core behavior.

Core Capabilities & API

• RESTful Endpoints – GET /api/products, POST /api/shoppinglist, etc., with authentication via session or token.
• Event Bus – Internal events (product.created, batch.expiring) can be listened to by plugins or external services.
• Webhooks – Configurable URLs that receive JSON payloads on specific events, enabling integrations with Home Assistant, IFTTT, or custom microservices.
• CLI Utilities – Artisan‑style commands (grocy:import-csv, grocy:update) can be executed in a Docker container or via SSH for automation scripts.

Deployment & Infrastructure

• Self‑Hosting – Requires a PHP 8.x runtime, SQLite (or any PDO‑compatible DB), and a web server with URL rewriting.
• Containerization – Official Docker image ships with pre‑configured Nginx, PHP-FPM, and SQLite; persistent data is stored in a bind mount (/config for settings, /data for the database).
• Scalability – While SQLite is sufficient for most households, switching to MySQL/PostgreSQL allows horizontal scaling; the API remains stateless, so multiple containers can be load‑balanced behind a reverse proxy.
• Backup & Restore – The data directory is the single source of truth; backup scripts or Docker volumes can be used for disaster recovery.

Integration & Extensibility

• Plugin System – Developers can create PHP plugins that register routes, modify the UI via Twig templates, or add new API endpoints.
• External Services – Barcode lookups can be extended to any REST API; the plugin interface allows adding new services without touching core code.
• Webhooks & Scripting – Trigger custom scripts on events (e.g., send an email when a product is about to expire).
• Custom UI – The front‑end is modular; developers can replace or augment components with React/Vue if desired, as the API remains stable.

Developer Experience

• Configuration – A single config.php file holds all runtime settings; defaults are documented in config-dist.php.
• Documentation – The README, website API docs, and inline PHPDoc provide clear guidance; community resources (Reddit, GitHub issues) are active.
• Community & Plugins – A growing ecosystem of add‑ons (e.g., Home Assistant integration, barcode services) demonstrates the platform’s extensibility.
• Licensing – Open‑source under MIT, encouraging commercial or internal use without license fees.

Use Cases

Advantages Over Alternatives

• **Performance