gatoserio/prepcouple repository overview

⁠PrepCouple

Self-hosted app to manage a household's reserve of food and essentials — for an emergency (outage, supply disruption) or a financial crisis. One small Docker image (Go + SQLite + embedded PWA), installable on Android (also as an APK), iOS and desktop. Interface in European Portuguese (PT-PT).

⁠What it will do

• Fast entry — scan a barcode, confirm quantity and expiry (month/year picker), done. Batch "chegou das compras" mode, one-tap +1/−1, FEFO consumption.
• Expiry alerts — "consumir primeiro" list, periodic checks for things without a printed date, daily/weekly digest via browser push, ntfy and email.
• How long can we last? — days of autonomy per scenario (emergência / crise financeira), naming the limiting factor (water, calories, protein).
• What is missing — coverage vs. target templates (Kit 72h, 2 semanas, 1–3 meses), automatic shopping list and a build-up plan for a monthly budget.
• Works offline — the full stock lives on the phone too; print a paper copy.
• Several households — members with roles, invites, and an instance admin panel.

⁠Run it

# docker-compose.yml (also in the repo root)
services:
  prepcouple:
    image: gatoserio/prepcouple:latest
    restart: unless-stopped
    user: "${UID:-65532}:${GID:-65532}"  # owner of ./data — mkdir it first
    ports: ["8090:8080"]
    environment:
      TZ: Europe/Lisbon
      # TRUSTED_PROXIES: 172.16.0.0/12   # your reverse proxy / tunnel network
    volumes: ["./data:/data"]

Open it, and the first screen creates your account (the instance administrator) and your household. Serve it over HTTPS (reverse proxy with Let's Encrypt, or Cloudflare Tunnel): the camera, browser push and the Android app need it. Behind a proxy, set TRUSTED_PROXIES so the real client IP and scheme are honored.

Footprint: a ~15 MB static binary in a distroless image, ~12 MB RAM idle.

⁠Develop

go run ./cmd/server                 # API on :8080
cd web && npm install && npm run dev  # UI with hot reload, proxies /api
go vet ./... && go test ./...         # backend tests
cd web && npm run test && npm run check

⁠Docs

• 01 — Domain model & features⁠
• 02 — Architecture decisions⁠
• 03 — Execution plan⁠

Sister project of FinCouple⁠.