Programmer Guide

This page is for people changing the code.

Stack

Backend: Express 5, CommonJS, Node.js.
Frontend: React 19, Vite, partial TypeScript.
Database: external Postgres through pg.
Tests: Jest/Supertest for backend, Playwright for e2e.
Package manager: npm.

Use Node.js 20.19+ or 22.12+ for frontend/Vite commands.

Repository Map

Key paths:

Path	Purpose
`backend/app.js`	Express middleware, CORS, route mounting, and error handler.
`backend/routes`	Route registration. Keep these thin.
`backend/controllers`	Request parsing and response handling.
`backend/models`	Database query modules.
`backend/services`	Domain service logic.
`backend/middleware`	Auth, RBAC, household access, request IDs, rate limits, image processing.
`frontend/src/api`	Axios API wrappers. Use these instead of direct component fetches.
`frontend/src/context`	Auth, household, store, settings, toast, and upload queue state.
`frontend/src/pages`	Route-level screens.
`frontend/src/components`	Shared and feature UI components.
`packages/db/migrations`	Canonical SQL migrations.
`.gitea/workflows`	Gitea Actions workflows.

Setup

npm ci
npm --prefix backend ci
npm --prefix frontend ci

Copy env examples as needed, but never commit real values:

backend/.env.example -> backend/.env
frontend/.env.example -> frontend/.env

Root migration scripts read DATABASE_URL from the shell environment.

Run Locally

Docker dev stack:

docker compose -f docker-compose.dev.yml up

Separate terminals:

npm run dev:backend
npm run dev:frontend

Default endpoints:

Backend: http://localhost:5000
Frontend through Docker compose: http://localhost:3010
Frontend direct Vite: http://localhost:5173

Coding Conventions

Preserve the current Express/Vite stack.
Keep route files thin.
Put DB-heavy logic in models/services.
Enforce RBAC and household access server-side.
Keep frontend network calls in frontend/src/api.
Use the shared Axios client so credentials are sent consistently.
Use context/hooks for UI state.
Frontend DB-mutating actions should show toast or bubble outcome notifications.
Progress notifications should reuse UploadQueueContext and UploadToaster.
Do not introduce cron, workers, polling daemons, or background job frameworks.
Do not add production dependencies unless the task clearly requires one and there is no practical existing option.

Auth Notes

The current login flow returns a token for compatibility and also creates a DB-backed session. The backend sets an HttpOnly session cookie. The Axios client sends credentials and also attaches the stored token when present.

When changing auth:

Keep sessions DB-backed.
Keep session cookies HttpOnly.
Do not log tokens or cookies.
Preserve redirect behavior for expired sessions.

Verification

Choose the narrowest useful checks first, then broaden when risk warrants it.

Common commands:

npm test
npm run lint
npm run typecheck
npm run audit
npm run build:backend
npm run build:frontend
npm run build
npm run test:e2e

Migration checks:

npm run db:migrate:status
npm run db:migrate:verify
npm run db:migrate:stale:check

Do not run npm run db:migrate unless an operator explicitly intends to apply migrations to the selected external database.

Tests To Add

Add or update tests when behavior changes:

API behavior: Jest/Supertest in backend/tests.
Authz, membership, invalid input, and not-a-member cases: include negative coverage.
UI behavior: focused Playwright tests in frontend/tests.
Pure docs changes: validate Markdown/content where practical.