Justinaquino: "Add Frappe HRMS wiki — main page + 9 chapters with Philippine localization"

2026-03-06T12:53:52Z

"Add Frappe HRMS wiki — main page + 9 chapters with Philippine localization"

New page

= Frappe HRMS =

<div style="background:#e8f4fd; border:1px solid #90caf9; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''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.<br/>
Upstream source: [https://github.com/frappe/hrms github.com/frappe/hrms]  |  Official docs: [https://docs.frappe.io/hr docs.frappe.io/hr]
</div>

== 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.

{| class="wikitable"
|-
! 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 ===

{| class="wikitable"
|-
! 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.

{| class="wikitable" style="width:100%;"
|-
! # !! 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

[[Category:ERPNext]]
[[Category:Frappe HR]]
[[Category:Human Resources]]
[[Category:Payroll]]
[[Category:Comfac]]

Frappe HRMS - Revision history

Justinaquino: "Add Frappe HRMS wiki — main page + 9 chapters with Philippine localization"