Repo:comfac-hrms/DataModel — Data Model & DocTypes

Overview

comfac-hrms contains 163 DocTypes (119 in HR module + 44 in Payroll module). DocTypes are Frappe's equivalent of database tables + forms + workflows combined.

Key DocTypes by Category

Employee Management (Masters)

DocType	Purpose	Key Fields	Links To
Employee	Core employee record (from ERPNext)	employee_name, department, designation, status, date_of_joining	Company, Department, Designation, Branch
Employee Grade	Job levels/ranks	grade_name, default_salary_structure	Salary Structure
Department	Organizational units	department_name, parent_department, company	Company, Employee (approvers)
Designation	Job titles	designation_name, skills	Skill
Branch	Office locations	branch, company	Company

Attendance & Time Tracking

DocType	Purpose	Key Fields	Type
Employee Checkin	Biometric/app check-ins	employee, log_type (IN/OUT), time, latitude, longitude	Transactional
Attendance	Daily attendance records	employee, attendance_date, status (Present/Absent), working_hours	Transactional
Attendance Request	Missed check-in corrections	employee, from_date, to_date, reason	Transactional
Shift Type	Work shift definitions	start_time, end_time, grace_period, allow_check_out_after_shift_end	Master
Shift Assignment	Employee shift schedules	employee, shift_type, start_date, end_date	Transactional
Timesheet	Project time tracking (ERPNext override)	employee, time_logs[], total_hours	Project, Task, Activity Type

Leave Management

DocType	Purpose	Key Fields	Links To
Leave Application	Leave requests/approvals	employee, leave_type, from_date, to_date, status	Employee, Leave Type, Leave Approver
Leave Type	Types of leave (Annual, Sick, etc.)	leave_type_name, max_days_allowed, is_carry_forward	—
Leave Period	Leave policy validity	from_date, to_date, company	Company
Leave Policy	Assignment rules	leave_policy_details[] (leave_type, annual_allocation)	Leave Type
Leave Policy Assignment	Employee leave entitlements	employee, leave_policy, effective_from	Employee, Leave Policy
Leave Ledger Entry	Leave balance tracking	employee, leave_type, transaction_type, leaves	Leave Type
Leave Encashment	Cash-out unused leave	employee, leave_type, encashment_days, encashment_amount	Employee, Leave Type
Compensatory Leave Request	OT to leave conversion	employee, work_from_date, work_to_date, leave_type	Employee, Leave Type

Expense & Advances

DocType	Purpose	Key Fields	Links To
Expense Claim	Employee expense reimbursement	employee, expense_date, total_claimed_amount, status, expenses[]	Employee, Cost Center, Project
Expense Claim Detail	Line items for claims	expense_type, amount, description, cost_center	Expense Claim Type, Cost Center
Employee Advance	Pre-approved cash advances	employee, purpose, advance_amount, paid_amount, claimed_amount	Employee
Gratuity	End-of-service benefits	employee, current_work_experience, gratuity_amount	Gratuity Rule, Employee
Gratuity Rule	Gratuity calculation formula	gratuity_rule_name, slabs[] (from_year, to_year, fraction_of_applicable_earnings)	—

Recruitment

DocType	Purpose	Key Fields	Links To
Job Opening	Published job positions	job_title, designation, department, status, published	Designation, Department
Job Applicant	Candidates	applicant_name, email_id, phone_number, status, resume_link	Job Opening
Job Offer	Employment offers	applicant_name, offer_date, proposed_start_date, status, designation	Job Applicant, Designation
Employee Onboarding	New hire process	employee, onboarding_template, activities[]	Employee, Employee Onboarding Template
Employee Onboarding Template	Reusable checklists	designation, department, activities[]	Designation, Department
Employee Separation	Offboarding process	employee, separation_template, activities[]	Employee, Employee Separation Template
Interview	Interview scheduling	job_applicant, interview_type, scheduled_on, status	Job Applicant, Interview Type

Performance Management

DocType	Purpose	Key Fields	Links To
Appraisal	Performance review	employee, appraisal_cycle, appraisal_template, final_score	Employee, Appraisal Cycle
Appraisal Cycle	Review periods	start_date, end_date, status	—
Appraisal Template	Evaluation forms	kra_categories[], goals[]	—
Appraisal Goal	Individual objectives	goal_name, description, weightage (0-5)	Appraisal
Appraisal KRA	Key Result Areas	kra, weightage	Appraisal Template
Employee Feedback	360-degree feedback	employee, reviewer, feedback_template, feedback_ratings[]	Employee

Payroll — Setup

DocType	Purpose	Key Fields	Links To
Salary Structure	Compensation templates	salary_structure_name, payroll_frequency, earnings[], deductions[]	Salary Component
Salary Structure Assignment	Employee compensation setup	employee, salary_structure, from_date, base	Employee, Salary Structure
Salary Component	Pay elements (Basic, HRA, etc.)	component_name, type (Earning/Deduction), formula	Account (GL)
Income Tax Slab	Tax brackets	effective_from, slab_name, slabs[] (from_amount, to_amount, percent)	—
Payroll Period	Tax year definition	start_date, end_date, company	Company

Payroll — Processing

DocType	Purpose	Key Fields	Links To
Salary Slip	Individual pay calculation	employee, posting_date, gross_pay, total_deduction, net_pay, earnings[], deductions[]	Employee, Salary Structure
Payroll Entry	Batch payroll processing	posting_date, department, branch, currency, salary_slips_created	Company, Cost Center
Additional Salary	One-time adjustments	employee, salary_component, amount, payroll_date	Employee, Salary Component
Employee Benefit Application	Flexible benefits	employee, benefits[] (component, amount)	Employee, Salary Component
Employee Incentive	Performance bonuses	employee, incentive_amount, payroll_date	Employee
Retention Bonus	Long-term retention	employee, bonus_amount, payable_on_date	Employee
Payroll Correction	Post-payroll adjustments	employee, payroll_entry, correction_reason, correction_amount	Payroll Entry, Employee
Full and Final Statement	Settlement on exit	employee, relieving_date, total_payable, total_receivable	Employee

Payroll — Taxation

DocType	Purpose	Key Fields	Links To
Employee Tax Exemption Declaration	Investment declarations	employee, payroll_period, declarations[] (exemption_category, amount)	Employee, Payroll Period
Employee Tax Exemption Proof Submission	Actual investment proofs	employee, payroll_period, submissions[]	Employee, Payroll Period
Employee Tax Exemption Category	Tax deduction categories	name (e.g., "80C", "HRA"), max_amount	—
Employee Other Income	Additional income sources	employee, payroll_period, amount	Employee, Payroll Period

Where DocType Definitions Live

File Path Pattern

hrms/[module]/doctype/[doctype_name]/[doctype_name].json

Example: hrms/hr/doctype/leave_application/leave_application.json

JSON vs Python

File Type	Purpose	When to Edit
`*.json`	Field definitions, permissions, UI layout	Adding fields, changing labels, modifying form layout
`*.py`	Business logic, validations, calculations	Changing how data is processed, adding validations
`*_list.js`	List view customization	Changing what appears in list views
`*_calendar.js`	Calendar view	For calendar-displayed DocTypes (Leave, Attendance)

Database Conventions

Table Naming

Frappe auto-generates table names:

tabLeave Application
tabSalary Slip
tabEmployee (from ERPNext)

Pattern: tab + DocType name with spaces

Safe Querying

Method	Use Case	Example
`frappe.get_doc()`	Single record with child tables	`frappe.get_doc("Leave Application", "HR-LAP-2024-00001")`
`frappe.get_all()`	Multiple records, read-only	`frappe.get_all("Employee", filters={"status": "Active"})`
`frappe.db.sql()`	Complex queries	Raw SQL (avoid if possible)
`frappe.get_list()`	List views with permissions	Respects user permissions

Key Data Patterns

Naming Series: Most transactional DocTypes use auto-generated IDs (e.g., HR-LAP-.YYYY.- → HR-LAP-2024-00001)
Status Field: Standard workflow states: Draft → Open → Approved → Rejected → Cancelled
Amendment: Submitted docs can be "amended" (cancelled + copied to new doc)
Child Tables: Stored in separate tables with parent and parenttype fields

Common Query Examples

Get Active Employees

employees = frappe.get_all("Employee", 
    filters={"status": "Active", "company": "ComFac Corporation"},
    fields=["name", "employee_name", "department", "designation"]
)

Get Leave Balance

leave_balance = frappe.get_all("Leave Ledger Entry",
    filters={
        "employee": "EMP-00001",
        "leave_type": "Annual Leave",
        "transaction_type": ["in", ["Leave Allocation", "Leave Application"]]
    },
    fields=["sum(leaves) as balance"]
)

Related Pages

Repo_comfac-hrms_Overview — Project overview
Repo_comfac-hrms_DirectoryMap — Directory structure
Repo_comfac-hrms_EntryPoints — How app starts, config files
Repo_comfac-hrms_ExtensionPoints — Hooks and customization
Repo_comfac-hrms_CommonEdits — Common edit recipes