Barcode Buddy: A PHP Barcode Bridge Between a Scanner and Grocy

The gap Barcode Buddy fills between a scanner and Grocy

Grocy is a self-hosted ERP for household inventory. It records what you have, where it is and when it expires, but its primary interface is a web application. A barcode scanner, by contrast, emits a string. Nothing in Grocy's own surface turns a scanned EAN or UPC into a stock movement without a human clicking through the matching product first. Barcode Buddy exists to close that gap: it takes a barcode, decides whether Grocy already knows the product, and if so calls the Grocy API to consume, add or open it. If the barcode is unknown, it looks the product name up through an external API and presents a choice in its own web UI. The audience is narrow and specific: people who already run Grocy, own a barcode scanner or an Android device, and want the physical act of scanning to become the data entry step. It is not a standalone inventory system and it does not store your stock. Grocy remains the database.

What happens when a barcode arrives

The README describes the core loop plainly. Barcodes are passed to Barcode Buddy, either manually through the web UI or automatically by grabbing input from a scanner. If the barcode is already in the Grocy system, Barcode Buddy triggers the matching action there: consume, add or open the product. If the barcode is unknown, the product name is looked up and a corresponding product can be chosen in the web UI. There is a second mechanism layered on top: tags can be saved, and if a new product contains the tag in its name, that product is already preselected in the drop-down list. That preselection is the part worth noticing. It means repeated scanning of unfamiliar items from the same brand or category converges on fewer clicks over time, without any machine learning or model training. The lookup itself relies on external services, with openfoodfacts.org and upcitemdb.com named in the acknowledgments as the barcode lookup APIs. So the unknown-barcode path has an external dependency: if those services do not recognise a code, the user is left with manual entry. The README does not describe a fallback for that case.

Running it: PHP, Docker, or an Android client

The prerequisites listed are a webserver that supports PHP (NGINX and Apache are given as examples), or Docker, plus a Grocy API key and ideally a barcode scanner or Android device. The README points to the Read the Docs documentation for installation and states that installation can be done in a couple of minutes, but the repository README itself does not reproduce the commands or config keys. What it does name are the distribution channels: bare metal, an Android client published on the Play Store and F-Droid under the package de.bulling.barcodebuddyscanner, a Docker image, a community-supported Kubernetes deployment, and a community-supported Home Assistant integration. The Docker section carries a warning in the README that the image name has changed, so anyone copying an older docker pull line from a blog post or an old compose file should check the current name against the documentation rather than assume it still resolves. The only configuration instruction stated directly in the README concerns reverse proxies: caching must be disabled, with a link to the setup page for details. That is a real constraint, not a formality. A caching proxy in front of an endpoint that receives scanner posts can serve a stale response or swallow a request, and the project treats this as important enough to call out in the top-level README.

The Android client and the scanner input path

Barcode Buddy is unusual in shipping a first-party Android client rather than leaving the mobile side to third parties. The README lists it as one of the available forms, with links to both the Play Store and F-Droid. That matters for the deployment decision: a phone with the client installed can act as the scanner, which removes the need for dedicated hardware in a kitchen or stockroom. The web UI also accepts manual barcode entry, so the system degrades to a lookup-and-click tool if no scanner is present. What the README does not explain is how the Android client authenticates against the PHP backend, whether it talks over the local network only, or what happens when the phone loses connectivity mid-scan. Those are the questions to answer from the documentation before relying on the mobile path in a setting where scans must not be lost.

Where Barcode Buddy is the wrong choice

The clearest limitation is structural: Barcode Buddy is an add-on to Grocy, so without a Grocy instance and an API key it has nothing to act on. Anyone looking for a standalone barcode inventory tool, a price comparison utility, or a scanner app that keeps its own database will find the prerequisites disqualifying rather than merely inconvenient. The second limitation is the unknown-barcode path. The README states that the product name will be looked up, with openfoodfacts.org and upcitemdb.com credited for the lookup API. Coverage on those services is uneven across regions and product categories, and the README does not claim otherwise. When a lookup fails, the workflow falls back to choosing a product in the web UI, which is exactly the manual step the tool was meant to remove. The third is operational: the project requires a PHP-capable webserver or Docker, and it must be reachable by whatever device is scanning. A caching reverse proxy is explicitly called out as something to configure around. None of these are defects in the code; they are boundaries of the problem it was built to solve, and they should be checked against your environment before installation rather than after.

How this differs from scanning directly into Grocy or building your own endpoint

Grocy itself is a web application with an API, and a technically inclined user could write a small script that takes a scanner's keyboard-wedge output and posts to that API directly. The difference in approach is where the decision logic lives. A direct script has to implement the unknown-barcode branch itself: which lookup service to call, how to present the candidate products, how to remember that a given brand usually maps to a given product. Barcode Buddy packages that branch, including the tag-based preselection rule and the web UI for resolving ambiguous codes. The cost of that packaging is a second service to run and maintain alongside Grocy, plus an Android client if you want the mobile path. The benefit is that the resolution workflow is a maintained component rather than a personal script. For a single user with a stable product set and no interest in the lookup fallback, a direct API call is less machinery. For a household where new products arrive regularly and someone has to decide what they are, the packaged workflow is the part that saves time.

Maintenance, release cadence and the AGPL-3.0 licence

The project is licensed AGPL-3.0, described in the README as AGPL3+, with the LICENSE.md file as the reference. The practical implication of the AGPL family is that if you modify Barcode Buddy and let users interact with it over a network, the licence's source-availability conditions can attach to your modified version. That is a general property of the licence, not legal advice, and anyone modifying and hosting it for others should read the licence text and take their own advice. On maintenance, the release history shows v1.9.0.0 dated 2026-09-03, preceded by v1.8.1.8 in June 2024 and v1.8.1.7 in September 2023. The gap between the 2023 and 2024 releases is roughly nine months, so this is not a project that ships weekly. The version numbering carries four components, which makes it hard to infer the size of a change from the number alone; the release notes are the place to check what moved. Upgrade cost is mostly operational rather than code-level: a Docker image pull or a file replacement on bare metal. The one upgrade hazard stated in the README is the changed Docker image name, which means an old compose file may silently keep pulling an outdated or missing image. Verify the current name before upgrading.

Editorial conclusion

Adopt Barcode Buddy if Grocy is already your inventory system of record and you want a scanner or Android device to drive consume, add and open actions without opening the Grocy web UI. Do not adopt it if you are not running Grocy, if you need a general-purpose barcode database, or if you cannot expose a PHP web endpoint that a scanner can post to. Before installing, verify three things: that your Grocy instance issues an API key, that your reverse proxy configuration disables caching for the Barcode Buddy paths, and that the Docker image name you plan to pull matches the current one, since the README warns the image name has changed.

Frequently asked questions

Official sources

1. Forceu/barcodebuddy on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases