Frappe HRMS
Frappe HRMS
Frappe HR is an open-source, modern HR and Payroll application built on the Frappe Framework. This wiki covers Comfac's deployment, configuration, and Philippine-localized usage of the platform.
Upstream source: github.com/frappe/hrms | Official docs: docs.frappe.io/hr
Overview
Frappe HRMS is a full-featured Human Resource Management System that ships as a Frappe app installed alongside ERPNext on a Frappe Bench server. It provides over 100 DocTypes organized into two top-level modules — HR and Payroll — covering the complete employee lifecycle from recruitment to separation.
Architecture
Frappe HRMS runs on the Frappe Framework (Python + JavaScript), which provides the database layer, REST API, role-based permissions, workflow engine, and scheduled task runner. ERPNext is a required dependency — the HRMS app extends ERPNext's Employee master, Company, and accounting integration rather than duplicating them.
| Layer | Component |
|---|---|
| Framework | Frappe Framework v17 (Python 3.10+) |
| Required app | ERPNext v17 |
| HRMS app | Frappe HR v17 (comfac-hrms fork) |
| Desktop UI | Frappe Desk (standard ERPNext desk) |
| Mobile PWA | Vue 3 + Ionic (employee self-service, check-in/out, leave, expense) |
| Shift Roster | Vue 3 + TypeScript SPA |
Key Capabilities
- Employee Lifecycle — from onboarding checklists and appointment letters through promotions, transfers, and full & final settlements
- Recruitment — staffing plans, job requisitions, job openings, multi-round interviews, offer letters
- Leave & Attendance — leave policies, earned leave, shift types, auto-attendance from biometric check-ins, roster management
- Expense & Travel — expense claims with multi-level approvals, employee advances, travel requests, vehicle logs
- Performance Management — appraisal cycles, KRAs, goal tracking, peer feedback
- Payroll & Taxation — salary structures with formula-based components, batch payroll runs, income tax slabs, gratuity
- Philippine Localization — SSS, PhilHealth, Pag-IBIG, BIR withholding, 13th month pay, holiday pay, de minimis benefits (see section below)
Philippine Localization Features
Philippine labor law and government-mandated contributions require specific payroll configurations not present in the default Frappe HRMS setup. The items below describe what must be configured in Comfac's instance.
Government Mandatory Contributions
| Contribution | Governing Body | Basis | Employee Share | Employer Share |
|---|---|---|---|---|
| SSS (Social Security System) | SSS | Monthly salary bracket table | Variable per bracket | Variable per bracket |
| PhilHealth | PhilHealth | 5% of basic monthly salary (2025 rate) | 2.5% | 2.5% |
| Pag-IBIG / HDMF | HDMF | 2% of monthly compensation (salary > ₱5,000); ₱100 otherwise | ₱100 – 2% | ₱100 – 2% |
Each of these is configured as a Salary Component (type: Deduction) with the relevant formula or lookup table. Employer shares are tracked separately as Salary Components on the employer side and posted to the appropriate liability accounts.
See: Frappe HRMS - Ch09 Philippine Localization
BIR Withholding Tax
- Tax is computed per the TRAIN Law (RA 10963) graduated tax table on taxable compensation income.
- Non-taxable items (13th month pay up to ₱90,000, de minimis benefits within thresholds) are excluded from the tax base.
- The Income Tax Slab DocType is used to encode the graduated brackets.
- BIR Form 2316 (Certificate of Compensation Payment/Tax Withheld) is generated annually per employee.
13th Month Pay
- Mandatory for all rank-and-file employees under PD 851.
- Computed as: Total basic salary paid for the calendar year ÷ 12.
- Up to ₱90,000 is exempt from income tax.
- Typically processed in November payroll as an Additional Salary component.
Holiday Pay
- Regular holidays (200%): Employee receives double the daily rate.
- Special non-working days (130%): Employee receives 130% of daily rate if worked.
- Configured via the Holiday List DocType with holiday type flags.
Night Differential
- Minimum 10% premium for work performed between 10:00 PM and 6:00 AM.
- Implemented as a formula-based Salary Component linked to timesheet or shift records.
Service Incentive Leave
- 5 days per year for employees who have rendered at least one year of service (Labor Code Article 95).
- Configured as a Leave Type with cash conversion enabled via Leave Encashment.
De Minimis Benefits
Tax-exempt fringe benefits within DOLE/BIR-prescribed limits:
- Rice subsidy (₱2,000/month or 50 kg)
- Medical cash allowance (₱1,500/semester)
- Uniform / clothing allowance (₱6,000/year)
- Laundry allowance (₱300/month)
- Achievement awards (₱10,000/year)
- Christmas / major anniversary gifts (₱5,000/year)
- Daily meal allowance for overtime (₱25/meal)
Each item within threshold is a non-taxable Salary Component; amounts in excess are treated as taxable.
Chapters
The full Frappe HRMS documentation is organized into the following chapters. Each page covers the DocTypes, workflows, prerequisites, and Comfac-specific configuration for that domain.
| # | Chapter | Summary |
|---|---|---|
| 1 | Frappe HRMS - Ch01 Recruitment | Staffing plans, job requisitions, job openings, applicant tracking, interviews, job offers, appointment letters |
| 2 | Frappe HRMS - Ch02 Employee Lifecycle | Onboarding, promotions, transfers, separation, full & final statement, skills, grievances, daily work summary |
| 3 | Frappe HRMS - Ch03 Performance Management | Appraisal cycles, KRAs, goals, peer feedback, appraisal templates, employee performance feedback |
| 4 | Frappe HRMS - Ch04 Shift and Attendance | Shift types, auto-attendance, check-in/out, shift schedules, overtime, roster, attendance reports |
| 5 | Frappe HRMS - Ch05 Expense Claims | Expense claims, expense types, employee advances, travel requests, vehicle logs |
| 6 | Frappe HRMS - Ch06 Leaves | Leave types, leave policies, allocations, leave applications, compensatory leave, leave encashment |
| 7 | Frappe HRMS - Ch07 Payroll | Salary components, salary structures, payroll entry, salary slips, additional salary, arrears, gratuity |
| 8 | Frappe HRMS - Ch08 Tax and Benefits | Income tax slabs, tax exemption declarations, proof submission, employee benefits, retention bonus |
| 9 | Frappe HRMS - Ch09 Philippine Localization | SSS, PhilHealth, Pag-IBIG, BIR withholding, 13th month pay, holiday pay, night differential, de minimis |
Related Pages
- ERPNext HR Module Outline — earlier outline reference
- ERPNEXT Payroll POC 251212 — payroll proof-of-concept notes
- Frappe Links and References — upstream documentation links
- Comfac ERPNext Strategy Canvas (Expanded) — strategic context