Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (70 loc) · 4.82 KB

CLAUDE.md

File metadata and controls

95 lines (70 loc) · 4.82 KB

CLAUDE.md

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

Project Overview

RC Tracker is a project management and time tracking application. It manages clients, projects, deliverables, tasks, and development hours tracking.

Tech Stack

  • Framework: Next.js 16 (App Router, Turbopack default)
  • Runtime: Node.js 20.9+ (pinned in .nvmrc)
  • Database: PostgreSQL on Neon, accessed via Prisma 5
  • Authentication: Auth.js v5 (next-auth@5) with a Credentials provider and 6-digit OTP, JWT sessions
  • Email: Resend + React Email (@react-email/components)
  • UI: Radix UI primitives + shadcn/ui, Tailwind CSS
  • Forms: React Hook Form + Zod
  • State: Jotai
  • Editor: Tiptap / Novel
  • Lint: ESLint 9 flat config (eslint.config.mjs)

Development Commands

pnpm run dev               # Next dev (Turbopack)
pnpm run build             # Production build
pnpm run start             # Production server on port 8050
pnpm run lint              # ESLint
pnpm run seed              # Seed the database
pnpm exec prisma migrate dev --name <name>   # Create + apply migration on dev
pnpm exec prisma migrate deploy              # Apply pending migrations (prod)
pnpm exec prisma generate                    # Regenerate Prisma client

Architecture

Database Schema (prisma/schema.prisma)

Hierarchical data model:

  • Client → many Projects
  • Project → many Deliverables
  • Deliverable → many Tasks
  • Task → many Developments (time entries)
  • User has a role (admin / client / user) and an optional clientId linking to a Client
  • OtpToken stores 6-digit codes per user with expiresAt and usedAt

There is no Account / Session / VerificationToken table — sessions are JWT, not DB-backed.

Application Structure

  • Public: /login (2-step OTP form), /unauthorized, /legal/*
  • Admin Panel (/admin/*): CRUD for clients, projects, deliverables, tasks, developments, users — gated by role === "admin" in src/app/admin/layout.tsx
  • Client Portal (/[slug]/*): per-client views (projects, billing, pendings) — slug matches Client.slug
  • API Routes: only /api/auth/[...nextauth] (Auth.js handlers)

Key Patterns

  1. Auth helper: auth() from @/lib/auth returns the current session in server components / actions. signIn, signOut, and handlers are also exported from there.
  2. Service Layer (src/services/*): Prisma access. auth-services.ts owns OTP gen/verify; email-services.ts owns Resend.
  3. Server Actions: Form submissions and mutations live in *-actions.ts files next to the page; they call services and revalidatePath.
  4. Data Tables: Reusable TanStack Table components with filtering / sorting / pagination.
  5. Forms: React Hook Form + Zod schemas. Always seed defaultValues with empty strings / numbers — defaultValues: {} causes React 19 uncontrolled→controlled warnings.

OTP login flow (dev vs prod)

  • src/app/(auth)/login/login-form.tsx is a 2-step client form (email → 6 digits) using <InputOTP> from shadcn.
  • Server actions in src/app/(auth)/login/actions.ts: checkEmailAction, sendOtpAction, verifyOtpAction.
  • In development, sendOtpEmail (in src/services/email-services.ts) logs the OTP to the console instead of sending mail. In production it goes through Resend.
  • The verify action calls signIn("credentials", { email, otp, redirect: false }); the Credentials provider in src/lib/auth.ts re-validates the OTP and populates the JWT.

Environment Variables

Required:

  • DATABASE_URL — Neon pooled connection string (used at runtime).
  • DIRECT_DATABASE_URL — Neon direct connection string (used by Prisma for migrations / shadow DB; same URL as DATABASE_URL minus the -pooler host suffix).
  • RESEND_API_KEY — Resend API key.
  • EMAIL_FROM — sender (e.g. RCTracker <rctracker@raphauy.dev>).
  • NEXTAUTH_SECRET (or AUTH_SECRET) — JWT signing secret. Auth.js v5 reads either name.
  • NEXTAUTH_URL (or AUTH_URL) — app base URL. Same alias rule.

Legacy SMTP env vars (EMAIL_SERVER, EMAIL_PORT, EMAIL_USER, EMAIL_PASSWORD) are no longer read and can be removed from Vercel.

Path Aliases

  • @/* maps to ./src/*

Migrations on Neon

Neon's pooler can break prisma migrate dev's shadow database step. The fix is directUrl = env("DIRECT_DATABASE_URL") in schema.prisma (already configured).

Workflow when changing the schema:

  1. Edit prisma/schema.prisma.
  2. pnpm exec prisma migrate dev --name <change> — generates the SQL file under prisma/migrations/ and applies it to the dev Neon branch.
  3. Smoke-test in dev.
  4. After deploying to Vercel, prisma migrate deploy runs on the main Neon branch via the postinstall / deploy step.