Repository Guidelines

Project Structure & Module Organization

app/ holds the Next.js route tree, including route handlers and shared layouts; use the @/ alias for imports.
UI primitives live in components/ and supporting hooks, utilities, and types reside in hooks/, lib/, and types/.
Backend integrations (Prisma client, auth helpers) live under prisma/ and auth.ts; seed data is in seed_*.json.
Automated tests are split between tests/ (unit/integration with Vitest) and e2e/ (Playwright specs). Visual artifacts land in playwright-report/.
Infrastructure and tooling assets live in scripts/, k8s/, terraform/, and docs/; ml-service/ houses the auxiliary ML worker.

pnpm dev launches the Turbopack dev server with .env.local secrets.
pnpm build compiles the Next.js app; pnpm start serves the production build using .env.production.
pnpm lint, pnpm format:check, and pnpm circular cover linting, Prettier verification, and dependency cycle scans.
pnpm prisma:migrate + pnpm prisma:deploy manage schema changes; pnpm seed hydrates a local database.
pnpm test, pnpm test:watch, and pnpm test:e2e run Vitest and Playwright suites (headed/DEBUG variants available for troubleshooting).

TypeScript is mandatory; follow module-aliased imports (@/components/...) and prefer React Server Components when possible.
Prettier (3.x) and Next ESLint (9) enforce 2-space indentation, single quotes, and Tailwind class ordering—run pnpm format before large diffs.
Use PascalCase for React components, camelCase for functions/variables, SCREAMING_SNAKE_CASE for constants, and hyphenated filenames for routes.
Tailwind utility-first styling is standard; compose complex styles with clsx or class-variance-authority.

Place Vitest specs alongside code in tests/ using the <name>.test.ts pattern; prefer descriptive describe blocks for feature scopes.
Ensure new features ship with Vitest coverage or Playwright journeys when user flows change. Snapshot tests belong in Vitest, not Playwright.
For database-dependent tests, load fixtures through Prisma seed helpers and reset state in beforeEach via the provided utilities.

Follow Conventional Commits (feat(scope): summary, fix:, refactor(k8s):, etc.); keep subject ≤72 characters.
Squash noisy work-in-progress commits locally; retain meaningful history for review.
Pull requests must describe the change, link tracking issues, include test evidence (pnpm test/pnpm test:e2e output), and attach UI screenshots when altering the app/ surfaces.
Tag owners of affected areas (app/, ml-service/, k8s/) and highlight any migration or seed steps in the checklist.