Repository Guidelines

Project Structure & Module Organization

backend/ contains the unified Node/Express server (backend/unified-server.js) and core backend modules in backend/src/ (services/, routes/, middleware/, graphql/).
frontend/ is the React app; primary code lives in frontend/src/, and production artifacts are generated in frontend/build/.
backend/__tests__/ holds backend Jest tests. Cross-stack UI/API checks live in tests/ (*.spec.js for Playwright, Selenium scripts under tests/selenium/).
database/ and backend/migrations/ contain schema and seed/migration data. docs/ stores architecture and operational notes.

Install dependencies per package:
- npm ci
- cd backend && npm ci
- cd frontend && npm ci
- cd tests && npm ci
Run backend locally: cd backend && npm run dev (nodemon) or cd backend && npm start.
Run frontend locally: cd frontend && npm run dev.
Build frontend: cd frontend && npm run build.
Backend tests with coverage: cd backend && npm test -- --coverage --passWithNoTests.
Playwright E2E (local): cd tests && PLAYWRIGHT_BASE_URL=http://localhost:4032 npx playwright test.

Use JavaScript/React with 2-space indentation and existing semicolon style.
Prefer async/await; keep route handlers thin and push business logic into backend/src/services/.
Naming: camelCase for variables/functions, PascalCase for React components, kebab/camel names aligned to existing files.
Test naming: Jest files as *.test.js; Playwright files as *.spec.js.
Frontend linting follows react-scripts ESLint defaults (react-app config).

Primary frameworks: Jest (+ Supertest) for backend and Playwright for E2E. Selenium is available for supplemental UI checks.
Add or update backend tests for any API/service change; add Playwright coverage for user-facing flow changes.
Include happy-path and failure-path assertions. For new modules, target at least ~80% coverage.

Follow Conventional Commit style seen in history (feat:, fix:, chore:, docs:, optional scopes like chore(docs):).
Keep commits focused and include related migration/test updates.
PRs should include: concise summary, linked issue (if applicable), test commands run + outcomes, and screenshots for UI changes.
Ensure CI checks pass before merge (backend tests, frontend build, and security scan).

Never commit plaintext secrets. Keep local secrets in backend/.env; use encrypted env files where supported.
Do not commit logs, test artifacts, or DB backups (logs/, tests/test-results/, tests/playwright-report/, backups/).