The HR Module

Status: unreleased. This walkthrough documents the HR module on the feat/hr-module branch (PR #353). Everything below is verified against the code in the repository and the live branch sandbox — not the marketing copy. Nothing here has shipped to customers yet.

What this is, in one page

Dentolize already runs the front of a dental clinic — appointments, patients, invoices, accounting. This module adds the back office for the people who work there: a complete HR and payroll system built directly on top of the existing double-entry accounting engine.

It turns "we pay staff by hand in a spreadsheet" into a governed monthly cycle that a clinic manager can run from one screen and that lands, to the halalah, in the general ledger.

The five pillars

1. Employee master & org structure. Every user in the clinic gets a proper employee record: department, position, manager (reporting line), job grade, hire/termination dates, identity & compliance documents (national ID / iqama, passport, professional license) with expiry dates, emergency contact, and full banking details including IBAN. A live org chart is drawn from the reporting lines.

2. Leave, schedules & attendance. Tenure-based annual leave (KSA-style 21 → 30 days after N years), Ramadan and seasonal reduced-hours periods, overtime that must be pre-approved to be paid, a missing-checkout guard that caps a forgotten shift, and self-service leave requests with coverage warnings when too many people in a team are off at once.

3. Payroll money paths. Structured allowances and deductions, calendar-day proration for mid-month joiners and leavers, employee loans and advances, GOSI (social insurance, employee-withheld + employer-accrued), and monthly end-of-service gratuity accrual — all posted through the accounting engine to five new ledger accounts.

4. Payroll outputs. WPS / SIF export (the Mudad-style bank file Saudi payroll requires), printable payslips, opt-in payslip delivery over WhatsApp, and HR reports (leave liability, punctuality by branch, 12-month payroll-cost trend).

5. Talent hub (strategic HR). A lightweight applicant tracking system (vacancies + staged applications), onboarding / offboarding checklists, training records with expiries, disciplinary warnings with employee acknowledgement, performance reviews & goals, benefit plans & enrollments, and job-grade pay bands.

Plus a full clinic-mobile parity port, 537 hand-translated i18n keys across all 9 languages, and identity/banking fields masked for viewers who lack the right permission.

Why it is built the way it is

The defining design choice is that payroll is accounting. Rather than a side-ledger that "eventually reconciles," every payroll event — a salary paid, a loan disbursed, GOSI withheld, an end-of-service provision accrued — is posted as a balanced journal entry through the same resilient posting engine the accounting module already uses. Two rich seed runs in the PR report a balanced trial balance with gated subledgers at Δ0.

The second choice is Saudi-first, but configurable. GOSI rates, tenure-leave thresholds, and end-of-service accrual are Middle-East payroll conventions — but the rates and switches live in company settings, not hard-coded law. This walkthrough is careful to point out, honestly, where the code is a configurable approximation of statute rather than the statute itself.

How to read this site

• By team — one page written for how your role uses or presents the

feature. Start there if you're in marketing, sales, support, training, leadership, or QA.

• Feature Tour — real annotated screenshots captured from the live sandbox.
• In depth — one page per feature area: a plain-language Business view

first, then a Technical view with exact file:line references into the codebase.

• Glossary & Data Model — every term, every new database model, and the five

new ledger accounts.

A note on scope

This is a large PR — 22 commits consolidating a 37-item HR backlog. The visible diff (PR #353) contains the Prisma data model, the server plumbing (WPS export, the expiry cron, GOSI/EOS accounts, resilient-posting handlers, permissions, validation, GraphQL schema) and the complete clinic-mobile HR port. The server resolvers and the clinic-web "HR Hub" screens it drives live in the codebase this branch builds on (the accounting module). This walkthrough documents the feature as it actually runs end to end, grounded in the real files at the PR head.