Codex 5.3 Refactor Note: Canonical refactor plan: docs/CODEX-5.3-REFACTOR-PLAN.md. This document is retained for historical and implementation context during the refactor.

Project Context (OfferReview)

Last updated: 2026-02-05

This file summarizes the current state, decisions, and operational notes so future Codex sessions can act quickly and safely.

What this project is

• Next.js 16.1.4 app (App Router) called OfferReview (HR/manager workflow system).
• Prisma ORM used for DB access.
• App runs locally via npm run dev and in production via npm run build + next start (PM2 on VPS).

Key tech stack

• Next.js 16.1.4
• Prisma (6.x expected; avoid Prisma 7 unless config updated)
• Node 20.x
• DB: Postgres on VPS (current target). Local DB also Postgres.
• Resend for email sending.

Repo status / recent changes

• Latest commit on main: 0a7cb7e (Resend email helpers + invite email in resend-setup API).
• New helper file: src/lib/notifications/email.ts.
• Resend client: src/lib/notifications/resend.ts now uses RESEND_FROM_EMAIL or RESEND_FROM.

Environment variables (critical)

Local .env.local (dev):

• DATABASE_URL=postgresql://... (local Postgres)
• JWT_SECRET=...
• RESEND_API_KEY=...
• RESEND_FROM_EMAIL=...
• APP_NAME=OfferReview (optional)

VPS .env (prod):

• DATABASE_URL=postgresql://offerreview_user:***@localhost:5432/offerreview
• JWT_SECRET=...
• RESEND_API_KEY=...
• RESEND_FROM_EMAIL=...

Notes:

• Do NOT point local env to Hostinger MySQL. That caused login 500s.
• On VPS, ensure .env exists and is loaded by PM2/systemd.

Database + Prisma

• Provider should be postgresql in prisma/schema.prisma.
• Migration folder exists: prisma/migrations/20250205_init/migration.sql.
• If migrations missing on VPS, run: npx prisma migrate deploy.
• If Prisma fails with missing DATABASE_URL, .env isn't loaded.

Postgres permissions on VPS

• If you see permission denied for schema public, fix as postgres user:
  • ALTER DATABASE offerreview OWNER TO offerreview_user;
  • ALTER SCHEMA public OWNER TO offerreview_user;
  • GRANT ALL ON SCHEMA public TO offerreview_user;
  • ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO offerreview_user;

Deployment on VPS (current path)

• VPS OS: Ubuntu (plain OS)
• App folder: /var/www/offerreview
• PM2 process name: offerreview

Typical flow:

1. cd /var/www/offerreview
2. git pull origin main
3. Ensure .env is present
4. npm install
5. npx prisma generate
6. npx prisma migrate deploy
7. npm run build
8. Restart PM2:
   • pm2 delete offerreview
   • export $(grep -v '^#' .env | xargs)
   • pm2 start npm --name offerreview -- start
   • pm2 save

PM2 logs (VPS)

• pm2 logs offerreview --lines 50 --nostream
• Files: /root/.pm2/logs/offerreview-out.log and ...-error.log

Common errors previously seen:

• Environment variable not found: DATABASE_URL (PM2 not loading env)
• Cannot find module @prisma/client-... (Prisma client not generated after build)

Nginx / Adminer (VPS)

• Nginx reverse proxy to Node (port 3000).
• Adminer installed for DB inspection.
• If Adminer 404, ensure Nginx config includes:
  • location /adminer/ { alias /usr/share/adminer/; ... }
  • fastcgi_pass unix:/run/php/php8.3-fpm.sock; (note php8.3)
• Access: http://<server-ip>/adminer/

Authentication + audit log

• Audit log writes can fail if userId doesn't exist.
• Recent fix: writeAuditEvent now allows null userId when it doesn't exist.

Resend (email)

• API key and from email required.
• Helper functions are in src/lib/notifications/email.ts.

Known pitfalls

• Prisma v7 errors about datasource url: stick to Prisma 6.x unless you migrate config.
• Avoid Turbopack on low-resource servers (set NEXT_DISABLE_TURBOPACK=1).
• If login returns 500 locally, check .env.local points to local Postgres.

Quick local commands

• Start dev: npm run dev
• Build: npm run build
• Prisma generate: npx prisma generate
• Migrate deploy: npx prisma migrate deploy
• DB health check (Postgres): psql "$DATABASE_URL" -c "select 1;"