Domain deep dive — Payroll & HR (Singapore)

Purpose

Single D1 narrative for engineers changing payroll calculations, statutory compliance, or payroll reporting on this app. It ties together:

• Generated Payroll & HR DocType reference pages
• Payroll & HR module, Payroll Plus, Payroll Entry override
• Tutorial: Singapore payroll, Server scripts, Doc events (Salary Slip chain)

Stock ERPNext + custom scripts

Core documents (Salary Slip, Payroll Entry, Employee, Salary Component) follow ERPNext/HRMS semantics; Lee Kim logic lives mainly in leekimerp/scripts/ and hooks.py doc_events.

Domain boundary

In scope	Out of scope (link instead)
SG CPF, SHG, SDL, ceilings, contribution tables	Non-SG payroll regimes
Lee Kim Payroll Settings, Singapore Payroll Settings, Company Payroll	Full HRIS (leave, attendance product rules) — use ERPNext docs + your site config
Payboy import settings	Payboy SaaS itself
Custom reports under lee_kim_alliance_erp/report/	Xero AR — Finance & AR

DocType cluster (generated)

Use payroll-hr as the index of custom tables: CPF rates/ceilings, payslip presentation, Payboy bridge, salary detail children, etc.

Sub-theme	Examples
Statutory	singapore_payroll_settings, cpf_contribution_rates, cpf_ow_ceiling
Lee Kim config	lee_kim_payroll_settings, company_payroll, payslip_settings
Integrations	payboy_settings
Detail / reporting	salary_slip_details, lk_salary_detail, pay_item_details, generate_payroll_reports

Code map

Layer	Primary locations
Salary Slip	scripts/salary_slip.py — setup_payment_days, setup_pay_items, calculate_cpf_v2, calculate_shg, calculate_sdl, recalculate_net_pay, …
Other scripts	scripts/payroll_entry.py, scripts/employee.py, scripts/salary_component.py
Hooks	hooks.py — doc_events on Salary Slip, Employee, Payroll Entry, Salary Component
Helpers	hook_methods.py
Reports	Reports catalog — CPF advice, payroll summaries, payslip reports

Validation chain (reference)

Aligns with the diagram on Payroll & HR; order is load-bearing — do not reorder without full regression.

Overlay priority (for overlays.json)

Keys are DocType folder names (snake_case). See docs/doctype-overlays/overlays.json and docs/doctype-overlays/README.md.

Tier	DocType keys (representative)	Notes
Baseline	lee_kim_payroll_settings, singapore_payroll_settings, company_payroll, payboy_settings, payslip_settings, cpf_contribution_rates	Company payroll config, statutory tables, payslip UI, Payboy import
Extended	cpf_ow_ceiling, salary_slip_details, lk_salary_detail, pay_item_details, generate_payroll_reports, payroll_report_detail	OW ceilings, slip lines, SG settings component picks, batch reporting
Further	Other payroll-hr DocTypes (e.g. employee_salary_detail, custom_salary_detail)	Add overlays when tuning or support load justifies them

After editing overlays, run npm run generate:doctypes from docs/ and commit generated doctype-reference/** if your team tracks them.

Failure modes (where to look)

Symptom	First checks
Wrong CPF / net pay	Singapore Payroll Settings, CPF Contribution Rates, calculate_cpf_v2 inputs; Salary Component assignments
Payslip won’t submit	Full validate chain in Doc events — order of methods
Payroll Entry oddities	Payroll Entry override, scripts/payroll_entry.py
Report vs slip mismatch	Report query vs Salary Slip stored values; same Company and period

Logs: Frappe Error Log, MariaDB slow queries for heavy reports, bench worker logs for long runs.

Related

• Engineering deliverables — governance policies (orthogonal to this domain narrative)
• Payroll & HR — detailed script list and statutory drift
• Tutorial: Singapore payroll — F flowchart baseline (Diagram roadmap)
• Business logic flows — payroll row in flow index
• Domain documentation strategy
• Documentation upgrade roadmap
• Feature catalog — owning team for payroll rows