Repository Guidelines

Project Structure & Module Organization

The Next.js App Router lives in src/app; shared UI sits in src/components, domain logic in src/features, hooks in src/hooks, utilities in src/lib, and shared types in src/types. Database schema, migrations, and seeds reside in prisma. Static assets live in public. Playwright suites are in tests/e2e with fixtures in tests/fixtures. Root shell scripts handle seeding, deployment, and environment checks—keep them executable.

Build, Test, and Development Commands

npm run dev starts the Turbopack development server. npm run build produces a production bundle (triggering prisma generate via prebuild), and npm start serves it. npm run lint executes ESLint with Next.js presets. npm run test:e2e runs the Playwright suite; pass --project=chromium to target a browser. Database helpers (npm run db:push, npm run db:seed, npm run db:migrate) keep the Prisma schema aligned with your environment.

Coding Style & Naming Conventions

The project uses TypeScript (.ts/.tsx) and React function components. Use PascalCase for components, camelCase for helpers, and prefix hooks with use. Follow the two-space indentation and trailing comma style seen in the repo. Run npm run lint before pushing and resolve warnings for unused variables, any, accessibility, and image usage promptly.

Testing Guidelines

Playwright drives regression coverage from tests/e2e. Name specs after the user flow (for example, student-dashboard.spec.ts). Prefer data attributes to brittle selectors, and reuse fixtures from tests/fixtures. Run npm run test:e2e before opening a pull request, scoping to relevant flows with --grep when speed matters. When tests need seeded data, run the matching seed script (for example, npm run db:seed or scripts/seed-tutorial-articles.sh) so scenarios align with expectations.

Commit & Pull Request Guidelines

Commits in this repo follow short, imperative messages (e.g. Handle WebSocket upgrades in edge runtime). Limit each commit to a single concern and include generated assets—such as updated Prisma clients—when they change. Pull requests should summarise intent, link any issue or task, document manual validation, and attach UI screenshots or recordings for UI changes. Confirm lint, build, and Playwright checks succeed locally before requesting review.

Environment & Data Setup

Create a .env from .env.example and fill every required secret before running Prisma commands. Use scripts/verify-env.sh to confirm configuration completeness, and rely on seed helpers (npm run db:seed, scripts/seed-tutorial-articles.sh, or npx ts-node --transpile-only seed/seed-roadmap-assignments.ts) to populate local data. Do not commit .env files or local databases; use scripts/setup-vercel-env.sh and vercel:build when preparing environment variables for shared deployments.