Code Review

Follow these guidelines when reviewing code for this Next.js + Prisma application.

Review Checklist

Correctness & DX

Look for these issues in code changes:

• •Runtime errors: undefined access, unhandled promise rejections, missing null checks on optional Prisma fields
• •Validation gaps: FormData parsing without guarding missing/invalid fields
• •Error handling: throwing generic errors where UI needs actionable messages; leaking internal errors to the client
• •Time & timezone: using new Date() inconsistently for “today” semantics

Next.js App Router Patterns

• •Server vs client boundaries:
  • •Prefer Server Components by default
  • •Add "use client" only when required (state, effects, browser-only APIs, event handlers)
  • •Keep client components small; push data access and heavy work to server components/actions
• •Server Actions ("use server" in src/app/actions/*):
  • •Authenticate early via auth() from src/lib/auth.ts
  • •For admin-only actions, wrap with withAdminAuth() from src/lib/admin.ts
  • •After mutations that affect server-rendered pages, call revalidatePath(...) (see src/app/actions/admin.ts)
• •Route handlers (src/app/api/*):
  • •Validate input and return appropriate status codes
  • •Avoid doing business logic directly in the route; delegate to services

Service Layer (src/services/)

• •Keep business rules in services (not in components, actions, or route handlers)
• •Prefer stateless service methods (many services in this repo use static methods)
• •Keep Prisma access centralized and testable; avoid duplicating query logic across actions/pages

Prisma & Database

• •Prisma client: always import prisma from src/lib/prisma.ts (singleton pattern)
• •N+1 queries: watch for loops that call Prisma repeatedly; prefer include/select/where in (...)
• •Transactions: for multi-write operations, consider prisma.$transaction(...) to maintain invariants
• •Migrations: follow .claude/rules/database.md
  • •Never edit committed migrations; create a new migration instead

Authentication, Authorization, Security

• •Auth checks: ensure all mutations and sensitive reads require auth() (or admin wrapper)
• •Role checks: admin screens/actions should use the existing role plumbing (token role set in src/lib/auth.ts)
• •Secrets: never log credentials, tokens, or full environment configs
• •User input: validate and normalize user-controlled strings (zip code, units, ids)

Performance & UX

• •Over-fetching: avoid fetching unused fields; use select for large models
• •Client bundle: avoid turning large subtrees into client components; avoid adding heavy deps casually
• •UI feedback: for server actions triggered from client, ensure pending states (useTransition) and error states exist

Long-Term Impact

Flag for extra care / senior review when changes involve:

• •Prisma migrations (schema changes) or dangerous backfills
• •Auth/role logic (src/lib/auth.ts, src/lib/admin.ts, middleware)
• •Caching/revalidation changes that affect correctness
• •New dependency adoption (bundle size, licensing, maintenance)
• •External API calls (weather, analytics exports, etc.)

Feedback Guidelines

Tone

• •Be polite and constructive
• •Provide actionable suggestions with code examples
• •Phrase as questions when uncertain: "Have you considered...?"

Approval

• •Approve when only minor issues remain
• •Don't block PRs for stylistic preferences already covered by linters
• •Goal is risk reduction, not perfect code