Glossary & Data Model

Terms

GOSI — the General Organization for Social Insurance (Saudi social insurance). Here: an employee-withheld contribution and an employer-accrued contribution, at company-configurable rates (not hard-coded statute), posted to GOSI Payable (2130) / GOSI Employer Expense (5220).

End-of-service (EOS / mukafa'a / gratuity) — the lump sum owed to staff on leaving. Accrued monthly as a straight-line provision (half-month per year under 5 years' service, full month after) to End-of-Service Provision (2620) / Expense (5230), and paid out against that provision.

WPS / SIF — Wage Protection System; the SIF (Salary Information File) is the bank file listing each employee's basic/housing/other/deductions/net. Built from a processed run so its control total equals Total Net. See WPS Export.

Proration — paying a mid-month joiner or leaver by the fraction of the month's calendar days they were employed. Applies to fixed base and EARNING allowances, not to hourly base or fixed deductions.

Salary component — a recurring monthly allowance (EARNING, e.g. housing) or deduction (DEDUCTION), separate from base salary, optionally counted in the GOSI base.

Tenure leave — annual leave that steps up with service (e.g. 21 → 30 days after N years), blended day-accurately in the anniversary year.

Reduced-hours period — a Ramadan/seasonal window that starts later and shortens the working day, company-wide or per branch (SchedulePeriod).

Overtime approval — when enabled, overtime is only paid if a manager approves the day; unapproved overtime is dropped and can't leak into base pay.

Missing-checkout guard — a forgotten check-out caps the day at maxDailyWorkedHours (default 16h) and flags it auto-closed.

Coverage warning — a non-blocking alert on leave approval showing how many teammates (same department ∩ branch) are already off.

Doctor payout — doctors are paid base + commission via a separate settlement path; they skip GOSI, loans, allowances, and attendance in the run.

Resilient posting / outbox — the retry-and-recover mechanism (PendingPosting rows) that makes every ledger write crash-safe. See Automation.

computeLineNet — the single authoritative net-pay formula (payrollMath.js:15) shared by draft, line edit, and process.

The five new ledger accounts

Seeded in accounting/coaTemplate.js, role-mapped in accounting/accountRoles.js and accounting/posting/engine.js, with AP/AR/EXPENSE fallbacks.

New data model (packages/prisma/schema.prisma)

All models are company-scoped with audit fields (createdById, createdAt, updatedAt) unless noted. Line numbers are where the model is defined.

Master & org

• Department (:4265) — org unit; name unique per company; optional

managerId.

• Position (:4283) — job position; optional departmentId.
• EmployeeRecord (:4302) — 1:1 with User (userId @unique). Employment,

compliance IDs + expiries, emergency contact, banking (incl. iban), gradeId.

• JobGrade (:4567) — pay band; code, level, minSalary/midSalary/

maxSalary.

• File.expiryDate (:3402) — expiry on employee documents (+ documentType).

Compensation & payroll

• SalaryComponent (:3878) — recurring allowance/deduction; kind, amount,

inGosiBase.

• PayrollSettings (existing, :3830) — new fields: tenure leave, overtime

approval, maxDailyWorkedHours, gosiEmployeeRate/gosiEmployerRate, eosEnabled, molEstablishmentId/employerBankCode, WhatsApp toggles.

• SalaryProfile (existing, :4056) — new: gosiApplicable,

gosiBaseOverride.

• PayrollRunLine (existing, :4122) — new money fields: allowancesAmount,

otherDeductions, loanDeduction, gosiEmployeeAmount, gosiEmployerAmount, prorationFactor.

• Attendance (existing, :2214) — new: overtimeApproved, autoClosed.

Loans & end-of-service

• EmployeeLoan (:3908) — loan/advance; principal, monthlyInstallment,

balance, status, treasuryId.

• EmployeeLoanPayment (:3930) — a repayment; payrollRunLineId set when

withheld by payroll.

• EosAccrual (:3945) — monthly per-employee EOS provision (unique per

period).

• EosPayment (:3962) — EOS payout; provisionReleased.

Scheduling & leave

• SchedulePeriod (:3979) — reduced-hours season; reduceHoursBy,

startDelayHours, optional branchId.

• LeaveType / LeaveRequest / WorkSchedule / Holiday — existing

models the module builds on.

Talent

• Vacancy (:4356), JobApplication (:4383) — ATS.
• ChecklistTemplate (:4409), EmployeeChecklist (:4424) — onboarding/

offboarding.

• TrainingRecord (:4440), DisciplinaryWarning (:4464).
• PerformanceReview (:4488), PerformanceGoal (:4514).
• BenefitPlan (:4532), BenefitEnrollment (:4549).

New enums

SalaryComponentKind, EmployeeLoanKind, EmployeeLoanStatus, EmployeeType, VacancyStatus, ApplicationStage, ChecklistKind, WarningLevel, ReviewStatus, GoalStatus.

Key source locations

Web routes quick reference

/hr → /hr/overview · /hr/people · /hr/roster · /hr/attendance · /hr/payroll · /hr/leave · /hr/commission (+ /hr/commission/rates/:id) · /hr/talent · /hr/reports · /hr/org · /hr/settings · /people/profile/:id (employee profile, top-level).