# Project Map

This is the fast orientation map for Fiddy.

## Stack
- Backend: Express 5 on Node 20, CommonJS modules, PostgreSQL via `pg`.
- Frontend: React 19 + Vite, mostly JSX with partial TypeScript.
- Package manager: npm.
- Database: external on-prem Postgres. Migrations are canonical in `packages/db/migrations`.

## Root
- `PROJECT_INSTRUCTIONS.md`: source-of-truth constraints and delivery contract.
- `AGENTS.md`: concise Codex/human working guide.
- `DEBUGGING_INSTRUCTIONS.md`: required bugfix workflow.
- `package.json`: root DB, test, lint, typecheck, build, and e2e command entry points.
- `docker-compose.dev.yml`: local app containers with backend env loaded from `backend/.env`.
- `.gitea/workflows`: deploy workflows for `main` and `main-new`.
- `.github/copilot-instructions.md`: compatibility shim that points back to root instructions.

## Backend
- `backend/server.js`: starts the Express app.
- `backend/app.js`: middleware, CORS, route mounting, and error handling.
- `backend/build.js`: copies runtime backend files into `backend/dist` for the existing backend build script.
- `backend/routes`: Express routers.
- `backend/controllers`: request handlers.
- `backend/models`: database query modules.
- `backend/services`: domain service logic where present.
- `backend/middleware`: auth, optional auth, RBAC, request IDs, rate limiting, and image upload processing.
- `backend/utils`: logging, HTTP response helpers, cookies, redaction.
- `backend/tests`: Jest/Supertest tests run from the root Jest config.
- `backend/migrations`: legacy/reference SQL only; do not add new canonical migrations here.

## Frontend
- `frontend/src/main.tsx`: browser entry point.
- `frontend/src/App.jsx`: top-level routing and providers.
- `frontend/src/config.ts`: API base URL.
- `frontend/src/api`: API wrappers and shared Axios client.
- `frontend/src/context`: app state providers.
- `frontend/src/hooks`: reusable UI-facing hooks.
- `frontend/src/pages`: route-level pages.
- `frontend/src/components`: shared and domain UI components.
- `frontend/src/styles`: global, page, component, and theme CSS.
- `frontend/tests`: Playwright e2e tests.

## Database and Scripts
- `packages/db/migrations`: canonical SQL migration set.
- `packages/db/migrations/stale-files.json`: known skipped/stale migration filenames.
- `scripts/db-migrate*.js`: migration apply/status/verify/new/stale helpers.
- `docs/DB_MIGRATION_WORKFLOW.md`: operator runbook for DB changes.

## Documentation
- `docs/DEVELOPMENT.md`: setup, run, verification, and troubleshooting.
- `docs/AGENTIC_CONTRACT_MAP.md`: maps Next.js-oriented architecture language to the current Express/Vite stack.
- `docs/PLANS.md`: lightweight template for multi-step work.
- `docs/architecture`, `docs/features`, `docs/guides`, `docs/migration`: deeper reference docs.
- `docs/archive`: historical implementation notes; useful context, not necessarily current.

## Known Maintainability Hotspots
- `frontend/src/pages/GroceryList.jsx` is large and should be split only during focused UI work.
- `frontend/src/components/manage/ManageHousehold.jsx`, `backend/services/group-invites.service.js`, and `backend/models/group-invites.model.js` are also large enough to review carefully before editing.
- Some older README/guides may describe pre-session or pre-household behavior; verify against current code and root instructions before relying on them.