# Repository Guidelines

## Project Structure & Module Organization
- `src/` holds the React client: `App.js` bootstraps the main views (“Slots buchen”, Store-Watch) and composes feature-specific components (z. B. `DashboardView`, `StoreWatchPage`) plus hooks/utilities in neighboring folders.
- `public/` contains the static shell served during development; only add files that must be copied verbatim into the build output.
- `server.js` is the Express backend that serves the built client, exposes the REST APIs used by the UI (e.g. `/api/stores`, `/api/store-watch/*`, `/api/user/preferences/*`, `/api/location/nearest-store`) und persistiert Daten über die Stores in `config/`.
- `config/` stores generated runtime state (`<profileId>-pickup-config.json`, Admin-Settings, Preferences, Watcher etc.). Keep it writable but untracked so local credentials never leak.
- `build/` is created by `npm run build` and shipped by the Express server or Docker image; never edit files here manually.
- `docker-compose.yml`, `Dockerfile`, and `rebuildContainer.sh` encapsulate deployment; update them when server ports, env vars, or base images change.

## Build, Test, and Development Commands
- `npm install` – restore dependencies in `package.json`.
- `npm start` – launch the CRA dev server on port 3000 with live reload.
- `npm run build` – emit the production bundle into `build/`; run before `node server.js` or container builds.
- `npm test` – run React Testing Library suites in watch mode; append `-- --watch=false` in CI.
- `npm run check:foodsharing-api` – verify the Foodsharing endpoints used by the app against `https://foodsharing.de/api/doc`.
- `node server.js` – serve the prebuilt UI and REST API using values from `.env` (e.g., `PICKUP_TOPIC`, credentials, ports).
- `docker-compose up --build` – rebuild and start the containerized service, syncing the bundled UI and server.

## Required Close-Out Steps
- After changes to `server.js`, `services/`, `src/`, `Dockerfile`, `docker-compose.yml`, or the Foodsharing API integration, always run this sequence completely:
- `CI=true npm test -- --watch=false`
- `npm run build`
- `npm run check:foodsharing-api` when Foodsharing endpoints, payloads, or response mappings are affected
- `docker compose up -d --build`
- `curl http://localhost:3005/api/health` and confirm the response contains `"status":"ok"`

## Git & Deployment Workflow
- Before making any code, config, Docker, or documentation change, verify `git status --short` is clean. If it is not clean, stop and reconcile the current worktree first; the running Docker service on port 3005 is the relevant production reference when deciding which state to preserve.
- If the running Docker service contains changes that are not committed, compare its `/app` contents against the worktree, commit the Docker-live state, and push it before starting a new feature or fix.
- After every completed feature or fix, update `.commitmessage`, stage it with `git add -f .commitmessage`, create a conventional commit, and push `main`.
- Features and fixes must go live in Docker after the commit: run `docker compose up -d --build` and verify `curl http://localhost:3005/api/health` returns a JSON response containing `"status":"ok"`.
- Keep `config/`, credentials, request logs, HAR captures, and other runtime state out of commits unless explicitly requested.

## Coding Style & Naming Conventions
- Use 2-space indentation and Standard/Prettier-compatible formatting; rely on the CRA ESLint config (`react-app`, `react-app/jest`) for feedback.
- Favor functional React components with PascalCase filenames (`PickupConfigEditor.js`) and camelCase props/state keys.
- Keep config schema fields (e.g., `desiredWeekday`, `onlyNotify`) camelCase across client and API payloads.
- Prefer descriptive folder-local CSS files rather than global selectors; co-locate assets next to their component whenever possible.

## Testing Guidelines
- React Testing Library + Jest underpin `App.test.js`; add `<Component>.test.js` files alongside components to exercise rendering and validation.
- Initialize helpers inside `setupTests.js` to keep suites lean.
- Aim for meaningful edge cases (blank config, duplicate IDs, toggling `onlyNotify`). Pull requests should demonstrate passing `npm test` output or CI logs.

## Commit & Pull Request Guidelines
- Follow conventional commits (e.g., `feat: add notification panel`, `fix: debounce config saves`) and keep subjects ≤72 characters.
- After every change, refresh `.commitmessage` with the final commit text and ensure it is staged (e.g., `git add -f .commitmessage`) so tooling can reuse it automatically.
- Reference issues or API endpoints impacted inside the body, and describe user-visible changes plus verification steps.
- PRs must include: summary of API/UI changes, screenshots or JSON samples when modifying config shape, notes on new env vars, and confirmation that `npm test` and `npm run build` succeed.

## Security & Configuration Tips
- Store secrets in `.env`, not in version control; provide `.env.example` updates when new variables (ports, credentials) are introduced.
- The server writes to `config/pickup-config.json`; ensure the directory exists and has the correct permissions before deploying or running containers.