nalalangan/grocery-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e4774ecd6a
grocery-app/docs/PROJECT_MAP.md
Nico 767def37cf docs: improve project onboarding
2026-05-25 11:47:21 -07:00

3.3 KiB
Raw Blame History

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.