Code Review

---
name: code-review-a156ffbf7184
description: Perform code reviews for this No Name Running Club application (Next.js 16 App Router + React 19 + TypeScript + Tailwind CSS 4 + Prisma + NextAuth v5). Use when reviewing PRs/diffs, proposing architectural changes, or giving code quality feedback. Covers server actions/route handlers, service-layer patterns, Prisma queries & migrations, auth/role checks, caching/revalidation, security, and performance.
---

# 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