# Repository Guidelines

## Project Structure & Module Organization
- Current contents: React PWA (Vite + Tailwind) with an Express API, Vitest test suite, and supporting docs.
- Structure for new code and assets:
  - `src/` – React app (components, pages, context, lib, styles).
  - `server/` – Express API (auth, reports, mailer, Mongo integration).
  - `tests/` – Vitest suites; API tests via Supertest (`*.test.js`).
  - `public/` – static assets served by Vite.
  - `Docs/` – specifications and high-level summaries.
  - `dist/` – production build output (do not edit manually).
  - `assets/` – if adding new static files for docs/app, prefer placing them here.

## Build, Test, and Development Commands
- Use Node.js 20 (matches CI). Install deps with `npm ci` for reproducibility.
- Scripts (from `package.json`):
  - `npm run dev` – start Vite dev server for the web app.
  - `npm run server` – start the Express API locally.
  - `npm run build` – build the web app to `dist/`.
  - `npm run preview` – preview the production build.
  - `npm test` / `npm run test:watch` – run Vitest suites.
  - `npm run fmt` / `npm run fmt:check` – format/check with Prettier.
- Run API and web in separate terminals during development.

## Coding Style & Naming Conventions
- Prettier is configured via `.prettierrc.json`; run `npm run fmt`.
- JavaScript/TypeScript: camelCase variables/functions; PascalCase components/types.
- React: colocate by feature when practical; keep files small and focused.
- If you add ESLint or other tooling, document commands in `README.md` and add CI checks.

## Testing Guidelines
- Place tests under `tests/` using `*.test.js` (Vitest). Mirror `src/` and `server/` structure where helpful.
- API tests use Supertest against `server/app.js`.
- Aim for meaningful coverage (target 80%+) and fast, deterministic tests; mock external services (email, DB) where possible.

## Continuous Integration
- GitHub Actions workflow at `.github/workflows/ci.yml`:
  - Uses Node 20; installs deps with `npm ci`.
  - Runs format check, builds the web app, and runs tests.

## Commit & Pull Request Guidelines
- Use Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`.
- Example: `feat(expense): add monthly aggregation service`.
- PRs should include a clear summary, linked issues, screenshots/logs for UI/behavioral changes, and a checklist for tests/docs/breaking changes.

## Security & Configuration Tips
- Do not commit secrets or personal data. Use `.env` (see `.env.example`) and keep it out of version control.
- Server uses JWT, bcrypt, Nodemailer, and MongoDB; rotate keys on exposure and review token/cookie settings (`SameSite`, CSRF, rate limiting) for production.
- Review PDF/DOCX before adding for sensitive information.

## Agent-Specific Instructions
- Keep changes minimal and scoped; prefer surgical edits over broad refactors.
- Respect existing structure and file formats; avoid adding licenses or boilerplate.
- Before destructive actions (e.g., file deletions), confirm intent in an issue or PR.