Repository Guidelines

Project Structure & Module Organization

app/ holds the Next.js App Router pages, layouts, and route handlers.
components/ contains reusable UI components (PascalCase files like AchievementBadge.tsx).
context/, hooks/, lib/, and utils/ store shared state, hooks, service clients, and helpers.
schemas/ and types/ define Zod schemas and TypeScript types.
messages/ and i18n/ manage localization content and helpers.
__tests__/ contains unit, integration, and e2e suites (see subfolders like __tests__/e2e).
public/ stores static assets; scripts/ contains one-off maintenance tools.

pnpm dev: start the Next.js dev server on http://localhost:3000.
pnpm build / pnpm start: build and run the production server.
pnpm lint: run ESLint across the repo.
pnpm format: format with Prettier using repo settings.
pnpm test: run Vitest in CI mode.
pnpm exec playwright test: run Playwright e2e tests (uses playwright.config.ts).
pnpm emulator: start Firebase emulators with persisted data; see emulator:* scripts for cleanup.

TypeScript + ESM; keep files in .ts/.tsx.
Prettier rules: 2-space indentation, single quotes, semicolons, 80-char lines.
Components use PascalCase.tsx; hooks use useThing.ts; helpers use camelCase.
CSS Modules use *.module.css alongside components where needed.
When extracting logic into functions, move them into an existing helper module (or a new helper file) and add unit tests.
Prefer simple if statements with early returns for error handling and message extraction. Avoid nested ternaries, especially patterns like error instanceof Error ? ... : ....

Unit/integration tests live in __tests__/unit and __tests__/integration and use Vitest.
E2E tests live in __tests__/e2e and run with Playwright.
Name tests *.test.ts/*.test.tsx and keep fixtures/mocks in __tests__/fixtures/__tests__/mocks.

Follow Conventional Commits as seen in history: feat:, fix:, refactor:, test: (optional scope).
PRs should include a clear description, testing notes (commands + results), and linked issues.
For UI changes, add screenshots or short clips; for config changes, call out env vars touched.

Store secrets in .env.local and keep them out of commits.
Firebase configuration lives in firebase.json, firestore.rules, and storage.rules; prefer emulators for local work.