Orbit Edu Faculty Monthly Payroll Run, Emergency Advances & Bilingual Currency Payslips

1. Accounting Topology & System Architecture

The Orbit Edu Faculty Payroll subsystem resides in apps/api/src/modules/edu/services/staff-payroll.service.ts and staff-payroll-pdf.service.ts, surfaced via the bursar console at apps/edu/src/app/admin/staff/page.tsx. It provides an automated, transactional payroll execution engine that maintains balanced double-entry accounting records across all campus departments.

+----------------------------------------------------------------------------------------------------+
|                                  FACULTY PAYROLL DISBURSEMENT FLOW                                 |
|                                                                                                    |
|   +-----------------------+     +-----------------------+     +--------------------------------+   |
|   |  STAFF ROSTER & BASE  |     |  TIMEKEEPING DEDUCT   |     |  EMERGENCY ADVANCE REGISTER    |   |
|   |  - Basic Salary       |     |  - Unpaid Leaves      |     |  - Outstanding Advances        |   |
|   |  - Academic Allowance |     |  - Late Penalty Surch.|     |  - Monthly Installment Cut     |   |
|   |  - Medical & Travel   |     |  - Attendance Sync    |     |  - Principal Approvals         |   |
|   +-----------+-----------+     +-----------+-----------+     +---------------+----------------+   |
|               |                             |                                 |                    |
|               +----------------------+      |      +--------------------------+                    |
|                                      |      |      |                                               |
|                                      v      v      v                                               |
|                      +-----------------------------------------------+                             |
|                      |         PAYROLL COMPILATION PROCESSOR         |                             |
|                      |  apps/api/src/modules/edu/services/           |                             |
|                      |            staff-payroll.service.ts           |                             |
|                      +-----------------------+-----------------------+                             |
|                                              |                                                     |
|                      +-----------------------+-----------------------+                             |
|                      |                                               |                             |
|                      v                                               v                             |
|   +------------------------------------+   +---------------------------------------------------+   |
|   |   GENERAL LEDGER JOURNAL VOUCHER   |   |        BANK DEPOSIT ADVICE & VECTOR PAYSLIPS      |   |
|   |   - Debit: Faculty Salaries 5010   |   |   - English / Urdu Currency-in-Words Translation  |   |
|   |   - Credit: Staff Advances 1130    |   |   - Bank Advice Excel / PDF Clearing File         |   |
|   |   - Credit: Tax Withheld 2150      |   |   - Tamper-Evident Vector Payslips                |   |
|   |   - Credit: Bank Clearing 1010     |   |   - Guardian Portal Faculty Transparency          |   |
|   +------------------------------------+   +---------------------------------------------------+   |
+----------------------------------------------------------------------------------------------------+

1.1 Document Data Contracts

The payroll service produces structured, audit-ready data structures for commercial banking advice and individual faculty payslips:

export interface BankDepositAdviceDocument {
  batchReference: string;
  payrollMonth: string;
  generatedAt: string;
  bankName: string;
  totalBeneficiaries: number;
  totalDisbursementAmount: number;
  totalAmountInWords: string;
  rows: BankAdviceRow[];
}

export interface BankAdviceRow {
  serialNumber: number;
  employeeCode: string;
  employeeName: string;
  cnicNumber: string;
  bankAccountNumber: string;
  bankIban: string;
  netPayablePKR: number;
  narration: string;
}

export interface FacultyPayslipDocument {
  employeeId: string;
  employeeCode: string;
  fullName: string;
  designation: string;
  department: string;
  joiningDate: string;
  payrollMonth: string;
  basicSalary: number;
  allowances: {
    academicAllowance: number;
    medicalAllowance: number;
    conveyanceAllowance: number;
    specialDutyAllowance: number;
  };
  grossSalary: number;
  deductions: {
    unpaidLeaveDeduction: number;
    advanceSalaryInstallment: number;
    incomeTaxWithholding: number;
    providentFundDeduction: number;
  };
  totalDeductions: number;
  netSalary: number;
  netSalaryInWords: string;
}

2. Interactive Operator Interface

The Faculty Payroll Console enables bursars to preview department salary distributions, verify advance deductions, and trigger batch disbursements:

3. Financial Mechanics: Bilingual Currency-in-Words Engine

In commercial banking operations and legal accounting audits, numerical values must be complemented by verbatim currency translations to eliminate fraud and check-tampering. Orbit Edu implements a high-precision converter supporting values up to Crores:

function numberToWordsPKR(num: number): string {
  if (num === 0) return 'Zero Rupees Only';

  const ones = [
    '', 'One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight', 'Nine',
    'Ten', 'Eleven', 'Twelve', 'Thirteen', 'Fourteen', 'Fifteen', 'Sixteen',
    'Seventeen', 'Eighteen', 'Nineteen'
  ];
  const tens = [
    '', '', 'Twenty', 'Thirty', 'Forty', 'Fifty', 'Sixty', 'Seventy', 'Eighty', 'Ninety'
  ];

  function convertSection(n: number): string {
    if (n === 0) return '';
    if (n < 20) return ones[n];
    if (n < 100) return tens[Math.floor(n / 10)] + (n % 10 !== 0 ? ' ' + ones[n % 10] : '');
    return ones[Math.floor(n / 100)] + ' Hundred' + (n % 100 !== 0 ? ' ' + convertSection(n % 100) : '');
  }

  const crore = Math.floor(num / 10000000);
  const lakh = Math.floor((num % 10000000) / 100000);
  const thousand = Math.floor((num % 100000) / 1000);
  const remainder = Math.floor(num % 1000);

  let words = '';
  if (crore > 0) words += convertSection(crore) + ' Crore ';
  if (lakh > 0) words += convertSection(lakh) + ' Lakh ';
  if (thousand > 0) words += convertSection(thousand) + ' Thousand ';
  if (remainder > 0) words += convertSection(remainder);

  return words.trim() + ' Rupees Only';
}

3.1 Verification Examples

4. Double-Entry General Ledger Accounting Architecture

When StaffPayrollService.disbursePayrollRun() executes, the system generates balanced General Ledger Journal Vouchers to record the expense, reduce employee receivables, credit statutory tax liabilities, and clear the operational payroll bank account:

4.1 General Ledger Mapping Table

5. Operational Runbook: Payroll Compilation & Bank Disbursement

The monthly faculty payroll execution proceeds through three distinct phases: Review, Approval, and Disbursement.

Phase 1: Pre-Run Auditing & Attendance Reconciliation

1. Synchronize Staff Attendance:

   • Navigate to apps/edu/src/app/admin/staff/payroll and select Compile Monthly Payroll.
   • Select the target billing month (e.g., 2026-10).
   • The engine automatically cross-references biometric timekeeping records from Campus Supervision Duty Rosters & Invigilation Neutrality.
   • Unapproved leaves without pay (LWOP) generate pro-rated base salary deductions:

     PerDayDeduction = BasicSalary / TotalDaysInMonth
     

2. Emergency Advance Verification:

   • The system checks active advances in the StaffAdvance ledger.
   • For employees with active repayment schedules, the installment amount is automatically added to the deductions ledger.

Phase 2: Payroll Run Approval & PDF Generation

1. Supervisor Review:

   • The campus principal and bursar inspect the gross-to-net broadsheet.
   • Click Lock & Approve Payroll Run. The status advances to approved, preventing ad-hoc modifications to staff records.

2. Vector Payslip Generation:

   • StaffPayrollPdfService creates individual A4 portrait payslips for each faculty member.
   • Each payslip includes:
     • School crest and institutional registration.
     • Employee designation, department, and CNIC number.
     • Itemized earnings, allowances, and statutory deductions.
     • Verbatim netSalaryInWords string.
     • Digital verification QR code and bursar signature stamp.

Phase 3: Commercial Bank Deposit Advice Dispatch

1. Bank Advice File Compilation:

   • The bursar clicks Export Bank Advice (1Link Format).
   • The system generates an encrypted clearing file formatted with employee IBANs, CNICs, and exact net payable figures.
   • Transmitted directly to the corporate bank switch for bulk salary credit.

2. General Ledger Voucher Finalization:

   • Executing Disburse Payroll marks all staff allocations as paid and updates the General Ledger journal with transaction voucher number #JV-PAY-202610-001.

Phase 4: Operational Throughput & Calculation Latency

The payroll execution engine is benchmarked across full faculty cohorts during month-end closing:

6. Failure Modes & Recovery SOP

The following operational contingency protocols resolve edge-case payroll anomalies:

7. Cross-Vertical Internal Linkages

The faculty compensation subsystem coordinates with other core institutional modules:

• Campus Supervision Duty Rosters & Invigilation Neutrality — Reconciles morning gate and examination proctoring duties against attendance allowances.
• Composite Fee Challans & 1Bill Integration — Balances incoming institutional student fee inflows against outgoing monthly faculty payroll obligations.
• Universal Double-Entry General Ledger & Chart of Accounts — Synchronizes payroll expense vouchers with the centralized corporate balance sheet.
• Registrar 360 Student Dossier & Clearance Gates — Audits faculty clearance status before disbursing terminal gratuity and provident fund settlements.