feat: implement Benefits & Automatic Deductions Engine

[pope-h]

Benefits & Automatic Deductions Engine

Closes #152

Summary

Implements a flexible engine to handle non-salary payroll components like healthcare premiums, retirement contributions, and taxes. The engine calculates these deductions before submitting the final net pay to the Stellar network, and exposes an employee portal view of deduction breakdowns.

Features

• CRUD APIs for Benefit Plans and Deduction Rules with multi-tenant isolation
• Pre-payroll Draft Payslip generation showing Gross vs Net with itemized deduction lines
• Support for percentage-based and fixed-amount deductions
• Logic to route deducted funds to Company Treasury or Insurance Provider wallets
• Employee portal view to see a breakdown of their deductions

Backend Changes

• Migration: backend/src/db/migrations/021_create_benefits_and_deductions.sql
  • Tables: benefit_plans, employee_benefit_enrollments, deduction_rules
  • Row-Level Security policies for tenant isolation
• Schemas: backend/src/schemas/benefitsSchema.ts
  • Zod validation for all request payloads
• Service: backend/src/services/benefitsService.ts
  • CRUD for benefit plans, enrollments, deduction rules
  • generateDraftPayslip: combines deduction rules and tax rules, routes funds to wallets
• Controller: backend/src/controllers/benefitsController.ts
  • REST handlers for CRUD, draft payslip, and employee deductions endpoint
• Routes: backend/src/routes/benefitsRoutes.ts → registered at /api/v1/benefits
  • JWT auth, role authorization, tenant context middleware
  • Employer endpoints scoped via :organizationId
  • Employee endpoint: GET /me/deductions

Frontend Changes

• Service: frontend/src/services/benefitsApi.ts
  • getMyDeductionsDraftPayslip wrapper
• Hook: frontend/src/hooks/useEmployeePortal.ts
  • Fetches and exposes deductionsDraft data
• UI: frontend/src/pages/EmployeePortal.tsx
  • New “Deductions Breakdown” card with Gross, Total Deductions, Net
  • Table listing each deduction line with type, amount, destination, and truncated wallet

API Endpoints

Employer (role: EMPLOYER)

• POST /api/v1/benefits/organizations/:organizationId/plans – Create benefit plan
• GET /api/v1/benefits/organizations/:organizationId/plans – List benefit plans
• PUT /api/v1/benefits/organizations/:organizationId/plans/:id – Update benefit plan
• DELETE /api/v1/benefits/organizations/:organizationId/plans/:id – Delete benefit plan
• POST /api/v1/benefits/organizations/:organizationId/enrollments – Upsert employee enrollment
• GET /api/v1/benefits/organizations/:organizationId/employees/:employeeId/enrollments – List enrollments
• POST /api/v1/benefits/organizations/:organizationId/deduction-rules – Create deduction rule
• GET /api/v1/benefits/organizations/:organizationId/deduction-rules – List deduction rules
• PUT /api/v1/benefits/organizations/:organizationId/deduction-rules/:id – Update deduction rule
• DELETE /api/v1/benefits/organizations/:organizationId/deduction-rules/:id – Delete deduction rule
• POST /api/v1/benefits/organizations/:organizationId/draft-payslips – Generate draft payslip

Employee (role: EMPLOYEE)

• GET /api/v1/benefits/me/deductions – Get current employee’s draft payslip with deduction breakdown

Security & Multi-tenancy

• All routes enforce JWT auth and role checks
• Tenant context middleware sets PostgreSQL session variable for RLS
• Controllers derive organization_id from URL params for employer routes
• Employee endpoint resolves employee by wallet_address from JWT

Testing

• Manual: Create benefit plans, enroll employees, add deduction rules, generate draft payslip, view in employee portal.
• Future: Add unit/integration tests for service/controller logic.

How to Use

1. As an employer, create benefit plans and deduction rules via the API.
2. Enroll employees in plans.
3. Generate a draft payslip to preview deductions and wallet routing.
4. Employees can view their deduction breakdown in the portal at the /me/deductions endpoint.

Review Checklist

• Migration includes RLS policies and indexes
• All CRUD operations validated with Zod
• Draft payslip calculation combines both deduction and tax rules
• Wallet routing resolves treasury/provider addresses
• Frontend renders breakdown and handles empty state
• Routes are registered and properly isolated
• Commits are signed and branch pushed

Ready for review and merge!

[Wilfred007]

@pope-h thank you for your contribution, kindly leave a star on the repo. Have a good day