Fiddy Wiki

Fiddy is a collaborative grocery list app for households. It lets people keep a shared shopping list, organize items by store location and zone, add product images, track recently bought items, and manage who can access each household.

This wiki is written for two audiences:

Users who shop with the app and manage households.
Programmers and operators who run, maintain, or extend the app.

Start Here

Audience	Page	Use it for
Users	User Guide	Sign in, create or join a household, use the grocery list, upload images, and adjust settings.
Household owners/admins	Households, Roles, and Invites	Manage members, invite links, join policies, and household roles.
Store/list managers	Stores, Zones, and Catalog Items	Add store locations, choose defaults, organize zones, and maintain reusable item suggestions.
Operators	Admin and Operations Guide	Manage system users, deployment, environment variables, and health checks.
Programmers	Programmer Guide	Set up the repo, run the app locally, follow coding conventions, and verify changes.
Programmers	Architecture and API	Understand the Express API, React client, auth, request IDs, and active route families.
Programmers/operators	Database and Migrations	Work with the external Postgres database and canonical migration workflow.
Everyone	Troubleshooting	Fix common login, household, store, image upload, CORS, and deployment issues.

What The App Does

Fiddy supports:

Email/password accounts with DB-backed sessions and an HttpOnly session cookie.
Multiple households per user.
Household roles: owner, admin, and member.
Invite links with join policies for closed, automatic, or approval-based joining.
Store locations per household, including default locations.
Ordered store zones so the list can match the shopping path.
Location-scoped grocery lists with quantities, notes, classification, and images.
Recently bought items for the last 24 hours.
Search and suggestions from the household/location catalog.
User settings for theme, list display, recent item count, confirmation behavior, haptics, and debug mode.
System administration for users and global store records.
Gitea Actions based build/deploy workflows.

Current Stack

Frontend: React 19 and Vite in frontend/.
Backend: Express 5 CommonJS API in backend/.
Database: external on-prem Postgres.
Package manager: npm.
Migrations: canonical SQL files in packages/db/migrations.
CI/CD: Gitea Actions in .gitea/workflows.

Important Concepts

The active app flow is household and location scoped:

A user signs in.
The user creates or joins a household.
The user selects a household store location.
The grocery list, item suggestions, zones, images, and recently bought items are scoped to that household and location.

Programmers should prefer the current scoped API routes under:

/households/:householdId/locations/:locationId/...

Some legacy global list routes still exist for compatibility, but new work should follow the household/location model unless the task explicitly says otherwise.