Homedepot

Homedepot is a private, responsive fridge inventory for the home network. Purchases, opened packs and consumed packs can be booked with a smartphone camera or by hand. Best-before dates are optional; multiple packs are tracked as lots.

Repository structure

An npm workspaces monorepo with a single package-lock.json at the root.

apps/
  web/                    Next.js application including the HTTP API and SQLite persistence
  ios/                    iOS app, built independently of the npm workspace
docs/
  api/openapi.yaml        API contract for every client
  features/               feature documentation (in German)
example-deployments/      standalone Docker Compose example

API

All endpoints live under /api/v1 and are described in docs/api/openapi.yaml:

Method	Path	Purpose
GET	/api/v1/health	availability of the application and its database
GET	/api/v1/products/lookup/{barcode}	resolve a product (local catalogue, otherwise Open Food Facts)
GET	/api/v1/inventory	current stock, product catalogue and recent movements
POST	/api/v1/inventory/purchases	store a purchase
PATCH	/api/v1/inventory/lots/{lotId}	correct a lot
POST	/api/v1/inventory/lots/{lotId}/open	open a lot
POST	/api/v1/inventory/lots/{lotId}/consume	consume one unit
POST	/api/v1/movements/{movementId}/undo	undo a movement

The web UI writes through Server Actions, which share the validation schemas in apps/web/lib/contract.ts and the domain layer with these routes.

Development

All commands run from the repository root:

npm install
npm run dev
npm run lint && npm run typecheck && npm test && npm run build

Without DATABASE_PATH the development database is created at apps/web/.data/homedepot.sqlite. Schema changes are stored as a migration with npm run db:generate. The supported environment variables are documented in apps/web/.env.example.

Docker

docker compose up -d --build

Reachable at http://SERVER-IP:3000, the iPad display at /ipad. For an installation without a local build, example-deployments/compose.yaml is standalone — that file plus Docker is all the target machine needs:

docker compose -f example-deployments/compose.yaml up -d

Important: Both configurations serve plain HTTP on port 3000, and browsers refuse camera access outside a secure context. For barcode scanning, publish the app through an HTTPS reverse proxy whose certificate every phone and tablet trusts.

Open Food Facts needs no API key. Optionally identify yourself via OPEN_FOOD_FACTS_USER_AGENT.

Backup

All state lives in the container volume at /data. Stop the container and back up the whole volume, or use the SQLite backup command while it runs — copying the files from a running container can capture an inconsistent state.