An NFC inventory for physical storage

A personal project, 2025 to now, and one of the apps running on the homelab cluster.

Why

Two problems, one app. The first is knowing which bin something is in without opening every bin to find out. The second is keeping records that are ready for an insurance claim before anything goes wrong: a serial number, a replacement value and a receipt for each item worth claiming.

Tags

Each bin carries a cheap 13.56 MHz NFC sticker. Chrome on Android reads the sticker's immutable factory UID through Web NFC, so nothing is ever written to a tag. The UID is the bin's identity.

Lesson learned: a handheld barcode and RFID scanner in keyboard-emulation mode is still supported, but as an optional accessory rather than the default. It is a UHF reader, and a UHF reader cannot read 13.56 MHz tags. Different band, no amount of configuration fixes that.

The core loop

Tap a bin to open it, then for each item either take a photo (the main path, since most things never get a tag) or scan a tag. With no bin open, a scan looks the item up and tells you where it lives, instead of creating an orphan item that belongs nowhere.

Background vision

After a photo upload, a background worker asks a self-hosted vision model to describe what is in the frame and writes the description to the item. The upload itself returns almost immediately, so nothing in the scan loop waits on a model. If the model is offline, the job is held and retried later, never dropped.

History

An audit walks a bin and marks each expected item present or missing, and anything found that wasn't expected as extra. Moves, audits and description changes each append an event, and committing an audit never wipes earlier history. Around that:

• Move all to… - empties a bin into another one in a single confirmed action, with a move event for every item
• Provenance - each item has a timeline of where it has been and what changed
• Collections - group items by purpose across bins, with a CSV export per collection
• Archiving - a bin can be archived once it is empty, and drops out of the pickers while keeping its history
• Conflicts - doing something that doesn't make sense, like moving an item into an archived bin, gets a clean 409 explaining why

Claim gaps

A claim gaps view lists every item missing a serial, a replacement value or a receipt, with each row linking straight to that item's edit page. It turns "am I covered?" into a to-do list.

Platform

• One Go binary, on SQLite or Postgres, with a Bootstrap UI
• SSO at the gateway through an ext_authz OIDC flow, with passkeys from the identity provider
• CSRF protection on every state change, rate limits, audit logging and CSP headers
• Deployed by GitOps to the homelab cluster, with Go and JavaScript test suites gating CI