# Repository Guidelines

## Project Structure & Module Organization
- `src/` holds the React client: `index.js` bootstraps the app, `PickupConfigEditor.js` manages form logic, and sibling files (`App.js`, `*.css`, `*.test.js`) live beside their concerns for easy discovery.
- `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 + MQTT bridge that serves the built client, exposes `/api/iobroker/pickup-config`, and persists data to `config/pickup-config.json`.
- `config/` stores generated runtime state. 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.
- `node server.js` – serve the prebuilt UI, REST API, and MQTT sync using values from `.env` (e.g., `MQTT_BROKER`, `MQTT_TOPIC`, `MQTT_USER`, `MQTT_PASSWORD`).
- `docker-compose up --build` – rebuild and start the containerized service, syncing the bundled UI and server.

## 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, API payloads, and MQTT messages.
- 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, validation, and MQTT payload shaping.
- 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 mqtt auth fields`, `fix: debounce config saves`) and keep subjects ≤72 characters.
- Reference issues or MQTT topics 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.