62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# 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.
|