View source for Repo comfac-hrms EntryPoints

= Repo:comfac-hrms/EntryPoints — Entry Points & Configuration =

== How This App Starts ==

=== Installation & Startup ===

Frappe apps are started by the Frappe Framework (via bench). The app itself doesn't have a traditional "main()" entry point. Instead:

# '''Bench''' loads the app via <code>hrms/__init__.py</code>
# '''Hooks''' (<code>hrms/hooks.py</code>) register the app with Frappe
# '''DocType definitions''' are loaded from JSON files
# '''Controllers''' (Python classes) are imported when needed

=== Key Commands ===

{| class="wikitable"
! Command !! Purpose
|-
| <code>bench --site [site] install-app hrms</code> || Install HRMS on a site
|-
| <code>bench --site [site] migrate</code> || Run patches, sync DocTypes
|-
| <code>bench start</code> || Start development server
|-
| <code>bench build</code> || Compile frontend assets
|}

== Main Config Files ==

=== hooks.py ===

'''Location:''' <code>hrms/hooks.py</code>

This is the '''most important file''' for understanding entry points. Key sections:

{| class="wikitable"
! Config Section !! What It Controls
|-
| <code>app_name</code>, <code>required_apps</code> || App identity and dependencies
|-
| <code>doctype_js</code> || Client scripts attached to ERPNext DocTypes
|-
| <code>override_doctype_class</code> || Python class overrides (Employee, Timesheet, etc.)
|-
| <code>doc_events</code> || Server-side event handlers (validate, on_update, on_submit)
|-
| <code>scheduler_events</code> || Background jobs (hourly, daily, weekly, monthly)
|-
| <code>website_route_rules</code> || URL routing for web views
|}

=== modules.txt ===

'''Location:''' <code>hrms/modules.txt</code>

Lists the modules: <code>HR</code> and <code>Payroll</code>. Controls how DocTypes are organized in the Frappe desk.

=== patches.txt ===

'''Location:''' <code>hrms/patches.txt</code>

List of database migration scripts that run during <code>bench migrate</code>.

== Environment Variables ==

Standard Frappe environment variables affect this app:

{| class="wikitable"
! Variable !! Purpose
|-
| <code>FRAPPE_BENCH_ROOT</code> || Path to bench installation
|-
| <code>MARIADB_ROOT_PASSWORD</code> || Database credentials (Docker setups)
|-
| <code>SITE_NAME</code> || Default site for commands
|}

== How to Verify It's Running Correctly ==

=== Health Checks ===

# '''Desk Access:''' Navigate to <code>/desk</code> — HR module should appear in the sidebar
# '''HR Module:''' Click "HR" — should see: Employee, Leave, Attendance, Expense Claims, etc.
# '''Payroll Module:''' Click "Payroll" — should see: Salary Slip, Payroll Entry, etc.

=== Log Locations ===

{| class="wikitable"
! Log Type !! Location (Docker) !! Location (Local)
|-
| Frappe web logs || <code>docker logs [container]</code> || <code>logs/web.log</code>
|-
| Scheduler logs || <code>docker logs [worker]</code> || <code>logs/worker.log</code>
|-
| Bench console || Terminal running <code>bench start</code> || Terminal running <code>bench start</code>
|}

=== What Healthy Startup Looks Like ===

* No import errors in logs
* HR and Payroll modules visible in desk sidebar
* DocTypes load without "Missing controller" errors
* Scheduled jobs registered (check <code>_rq_job</code> table or RQ dashboard)

== Request/Task Flow ==

=== Example: Submitting a Leave Application ===

# '''User Action:''' Clicks "Submit" on Leave Application form
# '''Client-Side:''' JavaScript validates fields (<code>leave_application.js</code>)
# '''API Call:''' <code>frappe.desk.form.save</code> endpoint called
# '''Server-Side (Controller):''' <code>LeaveApplication.validate()</code> runs
# '''Server-Side (Hooks):''' <code>doc_events</code> in hooks.py fire
# '''Database:''' Document saved, status changed to "Open" or "Approved"
# '''Background Job:''' Email notification queued (if configured)
# '''Response:''' Success message returned to client

=== Example: Payroll Entry Processing ===

# '''User Action:''' Creates Payroll Entry, clicks "Create Salary Slips"
# '''Controller:''' <code>PayrollEntry.create_salary_slips()</code> called
# '''Background Job:''' Salary slip creation queued (hourly_long queue)
# '''Individual Slips:''' Each <code>SalarySlip.calculate_net_pay()</code> runs
# '''Accounting:''' Journal Entry created (if configured)
# '''Status Update:''' Payroll Entry status changes to "Submitted"

== Integration Points ==

=== ERPNext Integration ===

* Expense Claims → Journal Entries (Accounting)
* Payroll → Bank Transactions (Payments)
* Employee → User (Access control)
* Timesheet → Projects (Billing)

=== Web Routes ===

* <code>/hrms</code> — HRMS frontend (Vue.js SPA)
* <code>/hr</code> — Roster module
* Job openings published via <code>website_generators</code>

== Related Pages ==

* [[Repo_comfac-hrms_Overview]] — Project overview
* [[Repo_comfac-hrms_DirectoryMap]] — Directory structure
* [[Repo_comfac-hrms_DataModel]] — DocTypes and data structures
* [[Repo_comfac-hrms_ExtensionPoints]] — Hooks and customization
* [[Repo_comfac-hrms_CommonEdits]] — Common edit recipes

[[Category:Repository Analysis]]