Merge pull request #2099 from Aakif-Kohari/feat/issue-2061-workers-comp-audit-engine

.gh_issues/pr_1813.md

@@ -0,0 +1,50 @@
+## Description
+
+This PR implements the Executive Deferred Compensation Plan (Section 409A NQDC) Ledger for executive pre-tax deferral management, FICA vs income tax bifurcation, and phantom benchmark compounding.
+
+* **Deferred Compensation Model** (deferredCompensation.model.js): Records executive deferral elections, phantom benchmark rates, accumulated balances, and scheduled multi-year distribution tranches.
+* **Deferred Compensation Service** (deferredCompensation.service.js): Calculates immediate FICA tax liabilities at deferral and compounds quarterly phantom growth yields.
+* **Deferred Compensation Controller & Routes** (deferredCompensation.controller.js, deferredCompensation.routes.js): Exposes /api/deferred-compensation/preview, /api/deferred-compensation/plans, and /api/deferred-compensation/plans/:id/accrue-interest.
+* **Tests & Documentation**: Added unit test suite and technical specifications document.
+
+---
+
+## Related Issue
+
+* Closes #1813
+
+---
+
+## Component(s) Affected
+
+* [x] Backend (ackend/)
+* [ ] Mobile app
+* [ ] Web app
+* [ ] Docs only
+* [ ] CI / tooling
+
+---
+
+## Type of Change
+
+* [x] New feature
+* [ ] Bug fix
+* [ ] Refactor
+* [ ] Other:
+
+---
+
+## Testing Performed
+
+* Tested principal deferral percentage calculation and FICA tax obligations.
+* Tested quarterly compounding growth yields against benchmark rates.
+* Verified input guardrails (1%-80% deferral caps).
+* Verified RBAC permissions for /api/deferred-compensation routes.
+
+---
+
+## Checklist
+
+* [x] Rebased from latest main - zero merge conflicts
+* [x] Clean and simple code with JSDoc comments
+* [x] No secrets committed

.gh_issues/pr_1814.md

@@ -0,0 +1,50 @@
+## Description
+
+This PR implements the Expatriate Cost of Living Allowance (COLA) & Housing Differential Engine for international assignments and global mobility payroll adjustments.
+
+* **Expat COLA Setting Model** (expatColaSetting.model.js): Configures city-pair price index ratios, spendable income tier percentages, housing allowance brackets, and hardship uplifts.
+* **Expat COLA Calculator Service** (expatColaCalculator.service.js): Calculates spendable income portions, destination index COLA supplements, housing excess differentials, and hardship allowances.
+* **Expat COLA Controller & Routes** (expatCola.controller.js, expatCola.routes.js): Exposes /api/expat-cola/preview, /api/expat-cola/settings, and /api/expat-cola/settings.
+* **Tests & Documentation**: Added unit test suite and mobility architecture specifications.
+
+---
+
+## Related Issue
+
+* Closes #1814
+
+---
+
+## Component(s) Affected
+
+* [x] Backend (ackend/)
+* [ ] Mobile app
+* [ ] Web app
+* [ ] Docs only
+* [ ] CI / tooling
+
+---
+
+## Type of Change
+
+* [x] New feature
+* [ ] Bug fix
+* [ ] Refactor
+* [ ] Other:
+
+---
+
+## Testing Performed
+
+* Tested spendable income isolation and destination price index scaling.
+* Tested housing norm differential subtraction and zero-flooring when host is cheaper.
+* Tested location hardship percentage additions.
+* Verified RBAC permissions for /api/expat-cola routes.
+
+---
+
+## Checklist
+
+* [x] Rebased from latest main - zero merge conflicts
+* [x] Clean and simple code with JSDoc comments
+* [x] No secrets committed

.gh_issues/pr_1815.md

@@ -0,0 +1,50 @@
+## Description
+
+This PR implements the Cross-Entity Intercompany Shared Services Payroll Billing & Transfer Pricing Engine for allocating centralized shared services costs across subsidiary entities with arm's length markups.
+
+* **Intercompany Payroll Billing Model** (intercompanyPayrollBilling.model.js): Records sending/receiving legal entities, direct labor allocations, transfer pricing markup percentages, and voucher settlement statuses.
+* **Intercompany Billing Service** (intercompanyBilling.service.js): Calculates subtotal direct costs, arm's length markups, and total billed settlement figures.
+* **Intercompany Billing Controller & Routes** (intercompanyBilling.controller.js, intercompanyBilling.routes.js): Exposes /api/intercompany-billing/preview, /api/intercompany-billing/vouchers, and /api/intercompany-billing/vouchers/:id/approve.
+* **Tests & Documentation**: Added unit test suite and transfer pricing architecture guide.
+
+---
+
+## Related Issue
+
+* Closes #1815
+
+---
+
+## Component(s) Affected
+
+* [x] Backend (ackend/)
+* [ ] Mobile app
+* [ ] Web app
+* [ ] Docs only
+* [ ] CI / tooling
+
+---
+
+## Type of Change
+
+* [x] New feature
+* [ ] Bug fix
+* [ ] Refactor
+* [ ] Other:
+
+---
+
+## Testing Performed
+
+* Tested direct labor + benefit cost subtotaling and markup calculations.
+* Tested markup range validation (0%-30% arm's length limits).
+* Verified approval workflows and status transitions.
+* Verified RBAC permissions for /api/intercompany-billing routes.
+
+---
+
+## Checklist
+
+* [x] Rebased from latest main - zero merge conflicts
+* [x] Clean and simple code with JSDoc comments
+* [x] No secrets committed

.gh_issues/pr_1816.md

@@ -0,0 +1,50 @@
+## Description
+
+This PR implements the Enterprise Tuition Reimbursement & Education Assistance Tax Exemption (Section 127) Tracker for educational assistance compliance, annual cap monitoring (,250), and automatic taxable perquisite spillover calculations.
+
+* **Tuition Reimbursement Model** (	uitionReimbursement.model.js): Records educational assistance claims, institutional accreditation, academic grades, and exempt vs taxable spillover splits.
+* **Tuition Assistance Service** (	uitionAssistance.service.js): Evaluates annual cumulative fiscal year claims against statutory limits (,250) and computes taxable spillover perquisites.
+* **Tuition Assistance Controller & Routes** (	uitionAssistance.controller.js, 	uitionAssistance.routes.js): Exposes /api/tuition-assistance/preview, /api/tuition-assistance/claims, and /api/tuition-assistance/claims/:id/approve.
+* **Tests & Documentation**: Added unit test suite and Section 127 compliance specifications document.
+
+---
+
+## Related Issue
+
+* Closes #1816
+
+---
+
+## Component(s) Affected
+
+* [x] Backend (ackend/)
+* [ ] Mobile app
+* [ ] Web app
+* [ ] Docs only
+* [ ] CI / tooling
+
+---
+
+## Type of Change
+
+* [x] New feature
+* [ ] Bug fix
+* [ ] Refactor
+* [ ] Other:
+
+---
+
+## Testing Performed
+
+* Tested 100% tax exemption for claims within the ,250 annual ceiling.
+* Tested exact taxable perquisite spillover calculation when crossing annual exemption limits.
+* Tested 100% taxable categorization for post-cap tuition claims.
+* Verified RBAC permissions for /api/tuition-assistance routes.
+
+---
+
+## Checklist
+
+* [x] Rebased from latest main - zero merge conflicts
+* [x] Clean and simple code with JSDoc comments
+* [x] No secrets committed

CONTRIBUTING.md

@@ -19,6 +19,12 @@ By participating in this project, you are expected to uphold our Code of Conduct
 
 ### 2. Set Up the Project Locally
 
+PaySphere uses **pnpm** as its package manager. Before proceeding, make sure you install it globally:
+
+```bash
+npm install -g pnpm
+```
+
 PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
 
 #### Backend Setup
@@ -29,7 +35,7 @@ PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
    ```
 2. Install dependencies:
    ```bash
-   npm install
+   pnpm install
    ```
 3. Create a `.env` file in the `backend/` directory based on the following template:
    ```env
@@ -41,7 +47,7 @@ PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
 4. Start the backend development server:
 
    ```bash
-   npm run dev
+   pnpm run dev
    ```
 
    The backend API will run on `http://localhost:5000` (or the port specified in your code).
@@ -51,7 +57,7 @@ PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
    permission definitions in `src/config/permissions.js`, re-seed by hand:
 
    ```bash
-   npm run seed
+   pnpm run seed
    ```
 
    Seeding is idempotent — running it repeatedly is safe. It also assigns the
@@ -65,7 +71,7 @@ PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
    ```
 2. Install dependencies:
    ```bash
-   npm install
+   pnpm install
    ```
 3. Create a `.env` file in the `frontend/` directory based on the following template:
    ```env
@@ -74,7 +80,7 @@ PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
    ```
 4. Start the frontend development server:
    ```bash
-   npm run dev
+   pnpm run dev
    ```
    The frontend will be accessible, typically at `http://localhost:5173`.
 
@@ -93,10 +99,10 @@ PaySphere is divided into a Node.js/Express backend and a React (Vite) frontend.
 PaySphere enforces strict code quality standards using ESLint and Prettier. To prevent CI failures and maintain a clean commit history, we use **Husky** and **lint-staged** to automatically lint and format your code before every commit.
 
 **Initial Setup (Required for all contributors):**
-After cloning the repository and running `npm install`, you **must** run the following command once to set up the Git hooks:
+After cloning the repository and running `pnpm install`, you **must** run the following command once to set up the Git hooks:
 
 ```bash
-npm run prepare
+pnpm run prepare
 ```
 
 This command initializes Husky and installs the pre-commit hook in your local `.git/hooks` directory.
@@ -113,7 +119,7 @@ This command initializes Husky and installs the pre-commit hook in your local `.
 If you want to format the entire codebase manually, you can run:
 
 ```bash
-npm run format
+pnpm run format
 ```
 
 **Bypassing the Hook (Not Recommended):**

backend/.env.example

@@ -1,4 +1,5 @@
 PORT=5000
+API_URL=http://localhost:5000
 MONGO_URI=your_mongodb_uri
 JWT_SECRET=your_secret_key
 GOOGLE_CLIENT_ID=your_google_id

backend/jest.config.js

@@ -1,4 +1,5 @@
 module.exports = {
   moduleDirectories: ['node_modules', '<rootDir>/node_modules'],
   transformIgnorePatterns: ['node_modules/(?!(\\.pnpm|@scure|@exodus|otplib))'],
+  setupFiles: ['<rootDir>/jest.setup.js'],
 };