tutor-management-app: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

yarn dev          # Start dev server (Next.js)
yarn build        # Production build
yarn lint         # ESLint (flat config in eslint.config.mjs)
yarn typecheck    # tsc --noEmit
yarn test         # Vitest

yarn db:migrate         # Run pending migrations
yarn db:migrate:undo    # Undo last migration
yarn set-password <email> <password> [name]   # Set a user's password (argv-based)

CI runs typecheck → lint → test → build before deploying (.github/workflows/deploy.yml).

Tests cover the pure logic only — src/lib/time.ts, generateSessions.ts, report.ts, and the zod schemas in validations.ts. There is no component or route test harness.

Architecture

MyClass is a private tutoring management app built with Next.js 15 App Router. It is Vietnamese-language, single-user by design (a tutor manages their own students). Required .env values are validated at boot by src/lib/env.ts (called from instrumentation.ts); see .env.example.

NEXT_PUBLIC_* variables are inlined at build time and .env is excluded from the Docker build context, so they are passed as build args in docker-compose.yml → Dockerfile. Adding a new one means editing all three places, or it silently ships as undefined.

Auth

NextAuth v5 with credentials provider (email + bcrypt password). Auth lives in auth.ts (full config) and auth.config.ts (edge-safe subset used by middleware). Sessions are JWT-based. src/middleware.ts must stay under src/ — Next.js ignores a root-level middleware.ts when the app lives in src/app. Its matcher excludes /api (those answer 401 JSON) and any path with a file extension (static assets and /sw.js).

Every API route starts with requireUser() from src/lib/auth-helpers.ts, then reaches data only through findOwnedStudent() / findOwnedBill() from the same file — never a bare findByPk. Both scope by createdBy and filter deletedAt. Mutating routes parse their body with parseBody(req, schema), and every error response is { error: string } via jsonError().