Offer Letter and Renewal System v0.3 — Complete Runnable Pack (Missing Endpoints + Seed + Minimal UI + Signature UI Spec)

App Version: 0.3.0 Last implementation update: 2026-07-14 This file closes the gaps from v0.2 so you can run end-to-end and serves as the runnable baseline for the current app shape.

Historical note:

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

0) Release identity

The current application version is sourced from package.json. predev and prebuild generate an immutable artifact containing version, Git SHA, build time, environment, and dirty-worktree state. No public version environment variable is required.

1) Current Implementation Notes (updated)

These are the implemented deltas in the current project state:

System now supports both Renewal and New Hire case types.
Offer extraction fills an editable employee profile and does not create an employee until HR confirms all required fields.
Department, role title, current grade, applicable grade, valid dates, positive salary values, three-letter currency, and a validated offer PDF are required before workflow progression.
Placeholder profile values are rejected; evaluation forms and performance reports cannot be uploaded as offer letters.
New-hire cases skip manager justification and performance snapshot requirements.
CEO can approve and sign new-hire cases once the latest offer letter is present.
CEO approval pages show a Decision Brief with proposed pay, annualized pay, contract term, same-grade quartiles and percentile, department/role cohorts, evidence signals, and an advisory approval posture before the decision controls.
PDF signer supports drag-and-drop placement with fit-width A4 rendering.
pdf.js worker is configured client-side for stable preview rendering.
Multi-signature placement flow is supported across multiple pages.
Finalization submits all saved placements in one request.
CEO signature management shows the current uploaded PNG preview and supports re-upload when the stored file is missing.
HR and CEO can re-upload a latest missing stored document from the case detail page to restore downloads or signing.
Production uploads must use a persistent UPLOAD_BASE_DIR such as /var/app/ers_uploads.
Digital mark is stamped under each signature:
- signed on: YYYY-MM-DD HH:mm UTC using Offer Letter and Renewal System
Signing is restricted to APPROVED cases only.
On successful signing:
- case transitions to SIGNED
- case is treated as closed/read-only
- active HR users are notified (in-app + email outbox)
If the signed offer is declined, CEO can mark the case DECLINED; linked approved compensation rows are voided, new-hire employee records are marked inactive, and the signed PDF remains available for audit.
CEO lands on /dashboard, HR on /hr/renewals, and Managers on /manager/requests.
Management analytics includes Executive Overview, Grade Curve, Increases & Outliers, and Budget & Risk views with persistent filters.
Management analytics can be viewed as a combined portfolio or filtered to Renewal-only or New-Hire-only cases.
Grade Curve supports table and accessible SVG chart modes. The chart renders current min/max, P25-P75, median, projected average, and clickable proposed-salary employee dots.
Analytics uses one effective compensation per active employee, prevents historical duplicate peer counting, separates future-effective pay, and discloses inferred/missing salary coverage.
Analytics excludes voided compensation and declined signed offers from default curves, peer stats, and committed budget impact.
Equivalent free-text grades are normalized for grouping; separate G grade scales are preserved.
Small peer groups are suppressed or marked limited, and open-ended 9999 terms are excluded from finite contract-term totals.
Large-increase percentage/amount, high-percentile threshold, and IDR/MYR rate are configurable in Admin Settings.
Filtered CSV analytics export is CEO-only, spreadsheet-safe, and audit logged.
AI contract review analyzes signature placement and contract variation against prior signed contracts, persists structured results, and offers suggestions inside the PDF signer.
CEO can request manager justification resubmission without rejecting the case.
HR and CEO see explicit missing-performance-snapshot states; a submitted manager justification does not bypass other renewal requirements.
Wrong documents and eligible pre-approval cases can be deleted with status and compensation guards; missing latest files can be recovered by re-upload.
Confirmed current-salary scale errors can be corrected with a guarded, before/after audit entry without changing proposed or approved compensation.
Authenticated pages use grouped responsive navigation, breadcrumbs, consistent page headers, and sticky section navigation on long case reviews.
Employee, status, grade, and department filters persist when a reviewer opens and returns from a case.
Role Help and About are available from the user menu; CEO System Health contains service checks.

2) Current Routes and Verification

Primary additions:

GET /dashboard?tab=curve&curveView=chart
GET /api/analytics/export
POST /api/renewals/:id/mark-declined
POST /api/renewals/:id/contract-ai-analysis
GET /api/documents/:docId/signature-suggestions

Run before deployment:

npm run test:analytics
npm run typecheck
npm run lint
npm run build
npx prisma migrate deploy

Production service:

systemctl restart ers-prod.service
systemctl is-active ers-prod.service