@classytic/payroll 1.0.0 → 2.8.0

package/README.md

@@ -1,574 +1,535 @@
-# 🎯 HRM Library - Human Resource Management
-
-Modern, flexible, production-ready HRM system following Stripe/Passport.js architecture patterns.
-
-## 🌟 Key Features
-
-### Multi-Tenant Support
-- Same user can be employee in multiple organizations
-- Complete data isolation per tenant
-- Re-hiring support with full employment history
-
-### Smart Payroll
-- **Pro-rated calculations** (mid-month hires)
-- **Attendance integration** (unpaid leave auto-deduction)
-- **Automatic deductions** (loans, advances, tax)
-- **Bulk payroll processing**
-- **Transaction integration** (seamless with existing system)
-
-### Data Retention
-- **Auto-deletion**: PayrollRecords expire after 2 years (MongoDB TTL)
-- **Export before deletion**: Required export for compliance
-- **Configurable retention**: Adjust via `HRM_CONFIG`
-
-### Flexible Architecture
-- **Reusable schemas**: Merge with your custom fields
-- **Plugin system**: Adds methods, virtuals, indexes
-- **Clean DSL**: `hrm.hire()`, `hrm.processSalary()`, `hrm.terminate()`
-- **Dependency injection**: Models injected at bootstrap
-
-## 📁 Structure
-
-```
-lib/hrm/
-├── index.js                    # Public exports
-├── init.js                     # Bootstrap initialization
-├── hrm.orchestrator.js         # Clean API (Stripe-like)
-├── enums.js                    # Single source of truth
-├── config.js                   # Configurable settings
-│
-├── models/
-│   └── payroll-record.model.js # Universal payroll ledger
-│
-├── schemas/
-│   └── employment.schema.js    # Reusable mongoose schemas
-│
-├── plugins/
-│   └── employee.plugin.js      # Mongoose plugin (methods/virtuals)
-│
-├── core/                       # Domain business logic
-│   ├── employment.manager.js   # Hire/terminate operations
-│   ├── compensation.manager.js # Salary/allowance operations
-│   └── payroll.manager.js      # Payroll processing
-│
-├── factories/                  # Clean object creation
-│   ├── employee.factory.js     # Employee creation with defaults
-│   ├── payroll.factory.js      # Payroll generation
-│   └── compensation.factory.js # Compensation breakdown
-│
-├── services/                   # High-level operations
-│   ├── employee.service.js     # Employee CRUD + queries
-│   ├── payroll.service.js      # Batch payroll processing
-│   └── compensation.service.js # Compensation calculations
-│
-└── utils/                      # Pure, reusable functions
-    ├── date.utils.js           # Date calculations
-    ├── calculation.utils.js    # Salary calculations
-    ├── validation.utils.js     # Validators
-    └── query-builders.js       # Fluent query API
-```
-
-## 🚀 Quick Start
-
-### 1. Create Your Employee Model
-
-```javascript
-// modules/employee/employee.model.js
-import mongoose from 'mongoose';
-import { employmentFields, employeePlugin } from '#lib/hrm/index.js';
-
-const employeeSchema = new mongoose.Schema({
-  // Core HRM fields (required)
-  ...employmentFields,
-
-  // Your custom fields
-  certifications: [{ name: String, issuedDate: Date }],
-  specializations: [String],
-  emergencyContact: { name: String, phone: String },
-  // ... any other fields you need
-});
-
-// Apply HRM plugin (adds methods, virtuals, indexes)
-employeeSchema.plugin(employeePlugin);
-
-export default mongoose.model('Employee', employeeSchema);
-```
-
-### 2. Bootstrap Integration
-
-```javascript
-// bootstrap/hrm.js
-import { initializeHRM } from '#lib/hrm/index.js';
-import Employee from '../modules/employee/employee.model.js';
-import PayrollRecord from '#lib/hrm/models/payroll-record.model.js';
-import Transaction from '../modules/transaction/transaction.model.js';
-import Attendance from '#lib/attendance/models/attendance.model.js';
-
-export async function loadHRM() {
-  initializeHRM({
-    EmployeeModel: Employee,
-    PayrollRecordModel: PayrollRecord,
-    TransactionModel: Transaction,
-    AttendanceModel: Attendance, // Optional
-  });
-}
-```
-
-### 3. Use the HRM API
-
-```javascript
-import { hrm } from '#lib/hrm/index.js';
-
-// Hire employee
-const employee = await hrm.hire({
-  organizationId,
-  userId,
-  employment: {
-    employeeId: 'EMP-001',
-    type: 'full_time',
-    department: 'training',
-    position: 'Senior Trainer',
-    hireDate: new Date(),
-  },
-  compensation: {
-    baseAmount: 50000,
-    frequency: 'monthly',
-    allowances: [
-      { type: 'housing', amount: 10000 },
-      { type: 'transport', amount: 5000 }
-    ]
-  },
-  bankDetails: {
-    accountName: 'John Doe',
-    accountNumber: '1234567890',
-    bankName: 'Example Bank'
-  },
-  context: { userId: hrManagerId }
-});
-
-// Process salary (creates Transaction automatically)
-const result = await hrm.processSalary({
-  employeeId: employee._id,
-  month: 11,
-  year: 2025,
-  paymentDate: new Date(),
-  paymentMethod: 'bank',
-  context: { userId: hrManagerId }
-});
-
-// Bulk payroll (all active employees)
-const results = await hrm.processBulkPayroll({
-  organizationId,
-  month: 11,
-  year: 2025,
-  context: { userId: hrManagerId }
-});
-```
-
-
-## 🎨 Complete API Reference
-
-### Employment Lifecycle
-
-```javascript
-// Hire
-await hrm.hire({ organizationId, userId, employment, compensation, bankDetails, context });
-
-// Update employment details
-await hrm.updateEmployment({ employeeId, updates: { department: 'management' }, context });
-
-// Terminate
-await hrm.terminate({ employeeId, terminationDate, reason: 'resignation', notes, context });
-
-// Re-hire (same employee, new stint)
-await hrm.reHire({ employeeId, hireDate, position, compensation, context });
-
-// List employees
-await hrm.listEmployees({
-  organizationId,
-  filters: { status: 'active', department: 'training', minSalary: 40000 },
-  pagination: { page: 1, limit: 20 }
-});
-
-// Get single employee
-await hrm.getEmployee({ employeeId, populateUser: true });
-```
-
-### Compensation Management
-
-```javascript
-// Update salary
-await hrm.updateSalary({
-  employeeId,
-  compensation: { baseAmount: 60000 },
-  effectiveFrom: new Date(),
-  context
-});
-
-// Add allowance
-await hrm.addAllowance({
-  employeeId,
-  type: 'meal',
-  amount: 3000,
-  taxable: true,
-  recurring: true,
-  context
-});
-
-// Remove allowance
-await hrm.removeAllowance({ employeeId, type: 'meal', context });
-
-// Add deduction
-await hrm.addDeduction({
-  employeeId,
-  type: 'loan',
-  amount: 5000,
-  auto: true, // Auto-deduct from salary
-  description: 'Personal loan repayment',
-  context
-});
-
-// Remove deduction
-await hrm.removeDeduction({ employeeId, type: 'loan', context });
-
-// Update bank details
-await hrm.updateBankDetails({
-  employeeId,
-  bankDetails: { accountNumber: '9876543210', bankName: 'New Bank' },
-  context
-});
-```
-
-### Payroll Processing
-
-```javascript
-// Process single salary
-await hrm.processSalary({
-  employeeId,
-  month: 11,
-  year: 2025,
-  paymentDate: new Date(),
-  paymentMethod: 'bank',
-  context
-});
-
-// Bulk payroll
-await hrm.processBulkPayroll({
-  organizationId,
-  month: 11,
-  year: 2025,
-  employeeIds: [], // Empty = all active employees
-  paymentDate: new Date(),
-  paymentMethod: 'bank',
-  context
-});
-
-// Payroll history
-await hrm.payrollHistory({
-  employeeId,
-  organizationId,
-  month: 11,
-  year: 2025,
-  status: 'paid',
-  pagination: { page: 1, limit: 20 }
-});
-
-// Payroll summary
-await hrm.payrollSummary({
-  organizationId,
-  month: 11,
-  year: 2025
-});
-
-// Export payroll data (before auto-deletion)
-const records = await hrm.exportPayroll({
-  organizationId,
-  startDate: new Date('2023-01-01'),
-  endDate: new Date('2023-12-31'),
-  format: 'json'
-});
-```
-
-## 📊 Data Models
-
-### Employee (Your Model + HRM Fields)
-
-```javascript
-{
-  // Identity & tenant
-  userId: ObjectId,              // Links to User
-  organizationId: ObjectId,      // Multi-tenant isolation
-  employeeId: "EMP-001",         // Custom ID (unique per org)
-
-  // Employment
-  employmentType: "full_time",   // full_time, part_time, contract, intern
-  status: "active",              // active, on_leave, suspended, terminated
-  department: "training",
-  position: "Senior Trainer",
-
-  // Dates
-  hireDate: Date,
-  terminationDate: Date,
-  probationEndDate: Date,
-
-  // Employment history (re-hiring support)
-  employmentHistory: [{
-    hireDate: Date,
-    terminationDate: Date,
-    reason: String,
-    finalSalary: Number
-  }],
-
-  // Compensation
-  compensation: {
-    baseAmount: 50000,
-    frequency: "monthly",
-    currency: "BDT",
-
-    allowances: [
-      { type: "housing", amount: 10000, taxable: true },
-      { type: "transport", amount: 5000, taxable: false }
-    ],
-
-    deductions: [
-      { type: "loan", amount: 2000, auto: true }
-    ],
-
-    grossSalary: 65000,    // Auto-calculated
-    netSalary: 63000,      // Auto-calculated
-  },
-
-  // Bank details
-  bankDetails: {
-    accountName: String,
-    accountNumber: String,
-    bankName: String
-  },
-
-  // Payroll stats (pre-calculated)
-  payrollStats: {
-    totalPaid: 500000,
-    lastPaymentDate: Date,
-    nextPaymentDate: Date,
-    paymentsThisYear: 10,
-    averageMonthly: 50000
-  },
-
-  // YOUR CUSTOM FIELDS
-  certifications: [...],
-  specializations: [...],
-  emergencyContact: {...}
-}
-```
-
-### PayrollRecord (Universal Ledger)
-
-```javascript
-{
-  organizationId: ObjectId,
-  employeeId: ObjectId,
-  userId: ObjectId,
-
-  period: {
-    month: 11,
-    year: 2025,
-    startDate: Date,
-    endDate: Date,
-    payDate: Date
-  },
-
-  breakdown: {
-    baseAmount: 50000,
-    allowances: [...],
-    deductions: [...],
-    grossSalary: 65000,
-    netSalary: 63000,
-
-    // Smart calculations
-    workingDays: 30,
-    actualDays: 25,           // If joined mid-month
-    proRatedAmount: 41667,    // Pro-rated salary
-    attendanceDeduction: 0,   // From attendance integration
-    overtimeAmount: 0,
-    bonusAmount: 0
-  },
-
-  transactionId: ObjectId,    // Links to Transaction
-  status: "paid",
-  paidAt: Date,
-
-  // Export tracking
-  exported: false,            // Must export before TTL deletion
-  exportedAt: Date
-}
-```
-
-## ⚙️ Configuration
-
-```javascript
-// lib/hrm/config.js
-export const HRM_CONFIG = {
-  dataRetention: {
-    payrollRecordsTTL: 63072000,      // 2 years in seconds
-    exportWarningDays: 30,            // Warn before deletion
-    archiveBeforeDeletion: true,
-  },
-
-  payroll: {
-    defaultCurrency: 'BDT',
-    allowProRating: true,             // Mid-month hire calculations
-    attendanceIntegration: true,      // Unpaid leave deductions
-    autoDeductions: true,             // Auto-deduct loans/advances
-  },
-
-  employment: {
-    defaultProbationMonths: 3,
-    allowReHiring: true,              // Re-hire terminated employees
-    trackEmploymentHistory: true,
-  },
-
-  validation: {
-    requireBankDetails: false,
-    allowMultiTenantEmployees: true,  // Same user in multiple orgs
-  },
-};
-```
-
-## 🔑 Key Concepts
-
-### Multi-Tenant Architecture
-
-Same user can work at multiple gyms:
-```javascript
-// User "john@example.com" (userId: 123)
-// Works at Gym A
-{ userId: 123, organizationId: "gymA", employeeId: "EMP-001", status: "active" }
-
-// Also works at Gym B
-{ userId: 123, organizationId: "gymB", employeeId: "STAFF-05", status: "active" }
-```
-
-Indexes ensure uniqueness:
-- `{ userId: 1, organizationId: 1 }` unique
-- `{ organizationId: 1, employeeId: 1 }` unique
-
-### Re-Hiring Flow
-
-```javascript
-// Employee leaves
-await hrm.terminate({
-  employeeId,
-  reason: 'resignation',
-  terminationDate: new Date()
-});
-// status: 'terminated', data preserved
-
-// Employee comes back
-await hrm.reHire({
-  employeeId,
-  hireDate: new Date(),
-  position: 'Manager', // Optional: new position
-  compensation: { baseAmount: 60000 } // Optional: new salary
-});
-// status: 'active', previous stint added to employmentHistory[]
-```
-
-### Smart Payroll Calculations
-
-**Pro-Rating (Mid-Month Hire)**:
-```javascript
-// Employee hired on Nov 15
-// Working days: 15 out of 30
-// Base salary: 60,000
-// Pro-rated: 60,000 × (15/30) = 30,000
-```
-
-**Attendance Integration**:
-```javascript
-// Monthly salary: 60,000
-// Working days: 30
-// Attended days: 25
-// Absent days: 5
-// Daily rate: 60,000 / 30 = 2,000
-// Deduction: 5 × 2,000 = 10,000
-// Final: 60,000 - 10,000 = 50,000
-```
-
-**Auto Deductions**:
-```javascript
-compensation: {
-  baseAmount: 60000,
-  allowances: [{ type: 'housing', amount: 10000 }],
-  deductions: [
-    { type: 'loan', amount: 5000, auto: true },  // Auto-deduct
-    { type: 'tax', amount: 3000, auto: true }
-  ],
-  grossSalary: 70000,
-  netSalary: 62000  // 70000 - 5000 - 3000
-}
-```
-
-### Transaction Integration
-
-Every salary payment creates a Transaction:
-```javascript
-{
-  organizationId,
-  type: 'expense',
-  category: 'salary',
-  amount: 63000,
-  method: 'bank',
-  status: 'completed',
-  referenceId: employeeId,
-  referenceModel: 'Employee',
-  metadata: {
-    employeeId: 'EMP-001',
-    payrollRecordId: ObjectId(...),
-    period: { month: 11, year: 2025 },
-    breakdown: { ... }
-  }
-}
-```
-
-### Data Retention & Export
-
-PayrollRecords auto-delete after 2 years:
-```javascript
-// TTL index on PayrollRecord
-payrollRecordSchema.index(
-  { createdAt: 1 },
-  {
-    expireAfterSeconds: 63072000,  // 2 years
-    partialFilterExpression: { exported: true }  // Only if exported
-  }
-);
-
-// Export before deletion
-const records = await hrm.exportPayroll({
-  organizationId,
-  startDate: new Date('2023-01-01'),
-  endDate: new Date('2023-12-31')
-});
-// Marks records as exported, making them eligible for deletion
-```
-
-## 🎯 Design Philosophy
-
-- **Stripe/Passport.js inspired**: Clean DSL, dependency injection, reusable components
-- **Lightweight**: Not a complex ERP, gym-focused features only
-- **Multi-tenant**: Same user can work at multiple organizations
-- **Smart defaults**: Pro-rating, attendance integration, automatic calculations
-- **Production-ready**: Transaction integration, data retention, comprehensive error handling
-
-## ✅ Next Steps
-
-1. Test bootstrap initialization
-2. Create Fastify routes in `modules/employee/`
-3. Add API handlers
-4. Migrate existing staff from organization module
-5. Deploy and monitor
-
----
-
-**Built with ❤️ following world-class architecture patterns**
-**Ready for multi-tenant gym management**
+# @classytic/payroll
+
+HRM & Payroll for MongoDB. Multi-tenant, event-driven, type-safe.
+
+## Install
+
+```bash
+npm install @classytic/payroll mongoose @classytic/mongokit
+```
+
+## Quick Start
+
+```typescript
+import { createPayrollInstance } from '@classytic/payroll';
+
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .build();
+
+// Hire
+await payroll.hire({
+  organizationId,
+  employment: { email: 'dev@example.com', position: 'Engineer', hireDate: new Date() },
+  compensation: { baseAmount: 80000, currency: 'USD', frequency: 'monthly' },
+});
+
+// Process salary
+await payroll.processSalary({
+  organizationId,
+  employeeId,
+  month: 1,
+  year: 2024,
+});
+```
+
+## Package Exports
+
+| Entry Point | Description |
+|-------------|-------------|
+| `@classytic/payroll` | Main API: Payroll class, types, schemas, errors |
+| `@classytic/payroll/calculators` | Pure calculation functions (no DB required) |
+| `@classytic/payroll/utils` | Date, money, validation utilities |
+| `@classytic/payroll/schemas` | Mongoose schema factories |
+
+---
+
+## Employee Operations
+
+```typescript
+// Hire
+await payroll.hire({
+  organizationId,
+  employment: { email, employeeId, position, department, hireDate },
+  compensation: { baseAmount, currency, frequency },
+});
+
+// Get employee
+const emp = await payroll.getEmployee({ employeeId, organizationId });
+
+// Update employment
+await payroll.updateEmployment({
+  employeeId,
+  organizationId,
+  updates: { position: 'Senior Engineer', department: 'engineering' },
+});
+
+// Terminate
+await payroll.terminate({
+  employeeId,
+  organizationId,
+  terminationDate: new Date(),
+  reason: 'resignation',
+});
+
+// Re-hire
+await payroll.reHire({ employeeId, organizationId, hireDate: new Date() });
+```
+
+## Compensation
+
+```typescript
+// Update salary
+await payroll.updateSalary({
+  employeeId,
+  organizationId,
+  compensation: { baseAmount: 90000 },
+  effectiveFrom: new Date(),
+});
+
+// Add allowance
+await payroll.addAllowance({
+  employeeId,
+  organizationId,
+  allowance: {
+    type: 'housing',    // 'housing' | 'transport' | 'meal' | 'mobile' | 'medical' | 'bonus' | 'other'
+    amount: 2000,
+    taxable: true,
+  },
+});
+
+// Add deduction
+await payroll.addDeduction({
+  employeeId,
+  organizationId,
+  deduction: {
+    type: 'provident_fund',  // 'tax' | 'loan' | 'advance' | 'provident_fund' | 'insurance'
+    amount: 500,
+    auto: true,
+  },
+});
+
+// Update bank details
+await payroll.updateBankDetails({
+  employeeId,
+  organizationId,
+  bankDetails: { accountNumber, bankName, routingNumber },
+});
+```
+
+### Payment Frequencies
+
+Supports multiple payment frequencies with automatic tax annualization:
+
+| Frequency | baseAmount | Periods/Year | Example ($104k/year) |
+|-----------|------------|--------------|----------------------|
+| `monthly` | Monthly salary | 12 | $8,666.67/month |
+| `bi_weekly` | Bi-weekly wage | 26 | $4,000/bi-week |
+| `weekly` | Weekly wage | 52 | $2,000/week |
+| `daily` | Daily rate | 365 | $285/day |
+| `hourly` | Hourly rate | 2080 | $50/hour |
+
+Tax is calculated consistently: same annual income = same annual tax, regardless of frequency.
+
+## Payroll Processing
+
+```typescript
+// Single employee
+const result = await payroll.processSalary({
+  organizationId,
+  employeeId,
+  month: 1,
+  year: 2024,
+  paymentDate: new Date(),
+  paymentMethod: 'bank',
+  payrollRunType: 'regular',  // 'regular' | 'supplemental' | 'retroactive' | 'off-cycle'
+});
+// Returns: { employee, payrollRecord, transaction }
+
+// Bulk processing
+const bulk = await payroll.processBulkPayroll({
+  organizationId,         // Optional in single-tenant mode or with context.organizationId
+  month: 1,
+  year: 2024,
+  employeeIds: [],        // Optional: specific employees (default: all active + on_leave)
+  batchSize: 50,
+  concurrency: 5,
+  onProgress: (p) => console.log(`${p.percentage}%`),
+});
+// Returns: { successCount, failCount, totalAmount, successful[], failed[] }
+```
+
+### Duplicate Protection
+
+The package provides database-level duplicate protection via a unique compound index:
+
+```typescript
+// Unique index on: (organizationId, employeeId, period.month, period.year, payrollRunType)
+// With partial filter: { isVoided: { $eq: false } }
+
+// This allows:
+// - One active record per employee per period per run type
+// - Multiple run types in same period (regular + supplemental)
+// - Re-processing after voiding (requires restorePayroll() first)
+// - Re-processing after reversing
+```
+
+**Important**: Voided records require `restorePayroll()` before re-processing. Voided is a terminal state that preserves audit trail.
+
+## Two-Phase Export
+
+Safe export that only marks records after downstream confirms receipt:
+
+```typescript
+// Phase 1: Prepare (records NOT marked)
+const { records, exportId } = await payroll.prepareExport({
+  organizationId,
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-01-31'),
+});
+
+// Send to external system...
+
+// Phase 2a: Confirm success (marks records)
+await payroll.confirmExport({ organizationId, exportId });
+
+// Phase 2b: Cancel if failed (records stay unmarked)
+await payroll.cancelExport({ organizationId, exportId, reason: 'API error' });
+```
+
+## Void / Reverse / Restore
+
+```typescript
+// Void unpaid payroll (pending, processing, failed)
+await payroll.voidPayroll({
+  organizationId,
+  payrollRecordId,
+  reason: 'Test payroll',
+});
+
+// Reverse paid payroll (creates reversal transaction)
+await payroll.reversePayroll({
+  organizationId,
+  payrollRecordId,
+  reason: 'Duplicate payment',
+});
+
+// Restore voided payroll (blocked if replacement exists)
+await payroll.restorePayroll({
+  organizationId,
+  payrollRecordId,
+  reason: 'Voided in error',
+});
+```
+
+**Status Flow:**
+```
+PENDING → PROCESSING → PAID → REVERSED
+   ↓          ↓
+   └──→ VOIDED ←── FAILED
+         ↓
+       PENDING (restore)
+```
+
+## Leave Management
+
+```typescript
+// Request leave
+await payroll.requestLeave({
+  employeeId,
+  organizationId,
+  leaveType: 'annual',  // 'annual' | 'sick' | 'unpaid' | 'maternity' | 'paternity'
+  startDate: new Date('2024-03-01'),
+  endDate: new Date('2024-03-05'),
+  reason: 'Vacation',
+});
+
+// Approve
+await payroll.approveLeave({ leaveRequestId, organizationId, approverId: managerId });
+
+// Reject
+await payroll.rejectLeave({
+  leaveRequestId,
+  organizationId,
+  rejectedBy: managerId,
+  rejectionReason: 'Insufficient leave balance',
+});
+
+// Get balance
+const balance = await payroll.getLeaveBalance({ employeeId, organizationId });
+// { annual: { total: 20, used: 5, remaining: 15 }, sick: {...}, ... }
+```
+
+---
+
+## Pure Calculators (No DB Required)
+
+Import from `@classytic/payroll/calculators` for client-side or serverless:
+
+```typescript
+import {
+  calculateSalaryBreakdown,
+  calculateProRating,
+  calculateAttendanceDeduction,
+} from '@classytic/payroll/calculators';
+```
+
+### Salary Breakdown
+
+```typescript
+const breakdown = calculateSalaryBreakdown({
+  employee: {
+    hireDate: new Date('2024-01-01'),
+    terminationDate: null,
+    compensation: {
+      baseAmount: 100000,
+      frequency: 'monthly',
+      currency: 'USD',
+      allowances: [
+        { type: 'housing', amount: 20000, taxable: true },
+        { type: 'transport', amount: 5000, taxable: true },
+      ],
+      deductions: [
+        { type: 'provident_fund', amount: 5000, auto: true },
+      ],
+    },
+  },
+  period: {
+    month: 3,
+    year: 2024,
+    startDate: new Date('2024-03-01'),
+    endDate: new Date('2024-03-31'),
+  },
+  attendance: {
+    expectedDays: 22,
+    actualDays: 20,
+  },
+  config: {
+    allowProRating: true,
+    autoDeductions: true,
+    defaultCurrency: 'USD',
+    attendanceIntegration: true,
+  },
+  taxBrackets: [
+    { min: 0, max: 600000, rate: 0 },
+    { min: 600000, max: 1200000, rate: 0.1 },
+    { min: 1200000, max: Infinity, rate: 0.2 },
+  ],
+});
+
+// Returns PayrollBreakdown
+{
+  baseAmount: number,
+  allowances: Array<{ type, amount, taxable }>,
+  deductions: Array<{ type, amount, description }>,
+  grossSalary: number,
+  netSalary: number,
+  taxableAmount: number,
+  taxAmount: number,
+  workingDays: number,
+  actualDays: number,
+  proRatedAmount: number,
+  attendanceDeduction: number,
+}
+```
+
+### Pro-Rating
+
+```typescript
+import { calculateProRating } from '@classytic/payroll/calculators';
+
+const result = calculateProRating({
+  hireDate: new Date('2024-03-15'),
+  terminationDate: null,
+  periodStart: new Date('2024-03-01'),
+  periodEnd: new Date('2024-03-31'),
+  workingDays: [1, 2, 3, 4, 5],
+  holidays: [],
+});
+
+// Returns ProRatingResult
+{
+  isProRated: true,
+  ratio: 0.545,
+  periodWorkingDays: 22,
+  effectiveWorkingDays: 12,
+  reason: 'new_hire',
+}
+```
+
+---
+
+## Events
+
+```typescript
+payroll.on('employee:hired', (payload) => { /* { employee, organizationId } */ });
+payroll.on('employee:terminated', (payload) => { /* { employee, reason } */ });
+payroll.on('salary:processed', (payload) => { /* { payrollRecord, transaction } */ });
+payroll.on('payroll:completed', (payload) => { /* { summary, period } */ });
+payroll.on('payroll:exported', (payload) => { /* { exportId, recordCount } */ });
+```
+
+## Webhooks
+
+```typescript
+// Register webhook
+payroll.registerWebhook({
+  url: 'https://api.example.com/webhooks',
+  events: ['salary:processed', 'employee:hired'],
+  secret: 'your-secret',
+});
+
+// Verify signature in handler
+const signature = req.headers['x-payroll-signature'];
+const timestamp = req.headers['x-payroll-timestamp'];
+const signedPayload = `${timestamp}.${JSON.stringify(req.body)}`;
+const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+```
+
+---
+
+## Configuration
+
+### Multi-Tenant (Default)
+
+```typescript
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .withConfig({
+    payroll: {
+      defaultCurrency: 'USD',
+      attendanceIntegration: true,
+      allowProRating: true,
+      autoDeductions: true,
+    },
+  })
+  .build();
+
+// organizationId required on all operations
+await payroll.hire({ organizationId, employment, compensation });
+```
+
+### Single-Tenant
+
+```typescript
+const payroll = createPayrollInstance()
+  .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+  .forSingleTenant({ organizationId: YOUR_ORG_ID, autoInject: true })
+  .build();
+
+// organizationId auto-injected
+await payroll.hire({ employment, compensation });
+```
+
+---
+
+## Key Types
+
+```typescript
+import type {
+  // Documents
+  EmployeeDocument,
+  PayrollRecordDocument,
+  LeaveRequestDocument,
+
+  // Core types
+  Compensation,
+  Allowance,
+  Deduction,
+  PayrollBreakdown,
+  TaxBracket,
+  BankDetails,
+
+  // Params
+  HireEmployeeParams,
+  ProcessSalaryParams,
+  ProcessBulkPayrollParams,
+  ExportPayrollParams,
+
+  // Results
+  ProcessSalaryResult,
+  BulkPayrollResult,
+
+  // Enums
+  EmployeeStatus,      // 'active' | 'on_leave' | 'suspended' | 'terminated'
+  PayrollStatus,       // 'pending' | 'processing' | 'paid' | 'failed' | 'voided' | 'reversed'
+  PayrollRunType,      // 'regular' | 'supplemental' | 'retroactive' | 'off-cycle'
+  LeaveType,           // 'annual' | 'sick' | 'unpaid' | 'maternity' | 'paternity'
+  AllowanceType,       // 'housing' | 'transport' | 'meal' | 'mobile' | 'medical' | 'bonus' | 'other'
+  DeductionType,       // 'tax' | 'loan' | 'advance' | 'provident_fund' | 'insurance'
+  PaymentFrequency,    // 'monthly' | 'bi_weekly' | 'weekly' | 'daily' | 'hourly'
+  PaymentMethod,       // 'bank' | 'cash' | 'check'
+} from '@classytic/payroll';
+```
+
+---
+
+## Schemas
+
+```typescript
+import {
+  createEmployeeSchema,
+  createPayrollRecordSchema,
+  employeeIndexes,
+  payrollRecordIndexes,
+} from '@classytic/payroll/schemas';
+
+// Create with custom fields
+const employeeSchema = createEmployeeSchema({
+  skills: [String],
+  certifications: [{ name: String, date: Date }],
+});
+
+// Apply indexes
+employeeIndexes.forEach(idx => employeeSchema.index(idx.fields, idx.options));
+```
+
+---
+
+## Utilities
+
+```typescript
+import {
+  // Date
+  addDays, addMonths, diffInDays, startOfMonth, endOfMonth,
+  getPayPeriod, getWorkingDaysInMonth,
+
+  // Money (banker's rounding)
+  roundMoney, percentageOf, prorateAmount,
+
+  // Query builders
+  toObjectId, isValidObjectId,
+} from '@classytic/payroll/utils';
+```
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  PayrollError,
+  DuplicatePayrollError,
+  EmployeeNotFoundError,
+  NotEligibleError,
+  ValidationError,
+} from '@classytic/payroll';
+
+try {
+  await payroll.processSalary({ organizationId, employeeId, month, year });
+} catch (error) {
+  if (error instanceof DuplicatePayrollError) {
+    // Already processed for this period + run type
+  } else if (error instanceof EmployeeNotFoundError) {
+    // Employee doesn't exist
+  } else if (error instanceof NotEligibleError) {
+    // Employee not eligible (terminated, etc.)
+  }
+}
+```
+
+---
+
+## License
+
+MIT