Offer Letter and Renewal System v0.2 — Build Pack (Prisma + App Router + Core Skeletons)

App Version: 0.2.0 Current compatibility update: 2026-07-14 This file includes: env vars, folder structure, Prisma schema, middleware, auth helpers, storage, email, peer stats, pdf signing backend, and key route skeletons.

Historical note:

Product name is now Offer Letter and Renewal System.
This build pack keeps the original ERS-v0.2 filename for traceability.

0) Environment Variables (.env)

DATABASE_URL="postgresql://USER:PASSWORD@HOST:5432/ers?schema=public"

AUTH_JWT_SECRET="replace-with-long-random-secret"
AUTH_COOKIE_NAME="ers_session"

UPLOAD_BASE_DIR="/var/app/ers_uploads"
UPLOAD_MAX_MB="20"

EMAIL_FROM="hr@company.com"
RESEND_API_KEY="replace-with-resend-key"

INTERNAL_API_SECRET="replace-with-long-random-secret"

NEXT_PUBLIC_APP_URL="https://review.example.com"
OPENAI_API_KEY="optional-openai-key"
OPENAI_MODEL="gpt-4.1-mini"

Production note:

UPLOAD_BASE_DIR must be a persistent directory such as /var/app/ers_uploads.
Do not point uploads to /tmp in production.

1) Folder Structure

app/
  (auth)/login/page.tsx
  (app)/layout.tsx
  (app)/page.tsx
  (app)/dashboard/page.tsx
  (app)/hr/renewals/page.tsx
  (app)/hr/renewals/new/page.tsx
  (app)/hr/renewals/[id]/page.tsx
  (app)/manager/requests/page.tsx
  (app)/manager/requests/[id]/page.tsx
  (app)/ceo/renewals/page.tsx
  (app)/ceo/renewals/[id]/page.tsx
  (app)/ceo/signature/page.tsx
  (app)/admin/settings/page.tsx
  (app)/admin/system-health/page.tsx
  (app)/admin/audit/page.tsx
  (app)/admin/users/page.tsx
  (app)/help/page.tsx
  (app)/notifications/page.tsx

app/api/...
components/grade-curve-chart.tsx
lib/services/management-analytics.ts
lib/services/contract-ai-analysis.ts
lib/management-analytics-filters.ts
lib/grade.ts
prisma/schema.prisma
prisma/migrations/20260713071000_contract_ai_analyses/migration.sql
prisma/migrations/20260714090000_management_analytics/migration.sql
middleware.ts

2) Current Production Extensions

The v0.2 skeleton remains historical. The current implementation additionally includes:

CEO-only management dashboard with URL-persistent filters and four analysis tabs
CEO case-level Decision Brief with grade quartiles, percentile, salary deltas, comparison cohorts, evidence signals, and explainable advisory posture
case-type filtering for combined, renewal-only, and new-hire-only management analytics
grade-curve table and accessible SVG box-plot chart with clickable employee dots
one-current-compensation-per-employee selection and future-effective salary handling
grade-label normalization, MYR/IDR comparison, data coverage, and small-peer safeguards
department/manager budget breakdowns, exceptions, and audited CSV export
signed-offer decline action that voids approved compensation and excludes it from default analytics
AI contract variation review and PDF signature placement suggestions
missing-file recovery, document/case deletion guards, and justification resubmission
HR intake completeness enforcement for department, role, current/applicable grade, dates, salaries, currency, and validated offer PDFs
extraction review-before-create behavior and rejection of evaluation documents misclassified as offer letters
EmployeeCompensation.currency, ContractAiAnalysis, and ANALYTICS audit entity migrations
responsive grouped navigation, breadcrumbs, page headers, case section navigation, and preserved list-filter return paths
Semantic Versioning sourced from package.json, with generated Git/build metadata and no runtime-editable application version setting

Verification commands:

npm run prisma:generate
npm run test:analytics
npm run typecheck
npm run lint
npm run build
npx prisma migrate status