HR & Core Payroll

1. Employee Master Records

The HR module centres on the employee record, exposed through EmployeesListPage and EmployeeDetailPage. Each record captures a full personal profile rather than a thin name-and-email stub, so that downstream payroll and statutory modules have the identity data they need.

Personal information stored on an employee includes:

• Demographics — gender, marital status (including a widowed value), and nationality.
• Identity documents — national ID, passport, and SSN, alongside a tax ID captured elsewhere in the lifecycle.
• Contact details — both a personal email and a separate work email, plus an emergency contact.

Beyond the personal profile, the record holds employment details that place the person inside the organisation: employment type, current employment status, hire date, the manager the employee reports to, the assigned job position, a grade level, the notice period, and whether the role is remote or office based. Bank and payment information is also held on the employee so that payroll runs can pay salaries without re-keying account data.

Supporting documents are attached per employee through the employee-document capability, keeping contracts, certificates and identity scans alongside the master record instead of in a disconnected file store. Because every HR entity carries an organisation identifier and is protected by row-level security, one tenant can never read another tenant's employee data, which matters when the same record later feeds country-specific statutory forms that embed national identity numbers.

2. The Employment Lifecycle and Status History

SamvraCore models employment as a state machine rather than a single editable status field. An employee moves through a defined set of statuses: active, probation, confirmed, on_leave, notice_period, resigned, and terminated. The detail page surfaces quick actions that drive these transitions deliberately.

The three principal lifecycle actions are:

• Confirm Employment — moves a worker from probation to confirmed, closing out the probation-end date and the confirmation flow.
• Process Resignation — records a voluntary departure with a reason and a last working date.
• Terminate Employment — records an involuntary end with a termination date and reason.

Resignation and termination are treated as irreversible actions and are guarded by an explicit confirmation step, so an operator cannot end someone's employment with a stray click. Every transition is written to an employment status history: the system records which status changed to which, the timestamp, the reason supplied for the change, and the user who made it. The detail view renders this history as a timeline, giving HR a complete, attributable audit trail of a person's tenure.

This disciplined lifecycle is not cosmetic. Because country payroll engines compute gratuity, end-of-service benefit and final-settlement forms from service dates and cessation reasons, the accuracy of the hire, confirmation and termination records directly determines whether statutory exit documents are correct.

3. Departments, Job Positions and Organisation Structure

Two reference structures give the employee record its organisational context: departments and job positions.

Departments (DepartmentsPage) are arranged hierarchically and can nominate a head employee, so the structure reflects real reporting lines rather than a flat list of labels. Because departments nest, an organisation can model divisions containing sub-teams and still roll reporting up a single tree.

Job Positions (JobPositionsPage) define the roles employees occupy. A position carries a salary range and a grade level, which ties the HR catalogue to the compensation bands referenced on the employee record. The grade level stored on the employee is the same grade concept used by positions, keeping job architecture and individual records consistent.

These structures interact with the lifecycle and payroll layers in concrete ways. The reports-to field on an employee links individuals into the management chain that approval workflows can traverse — for example, routing a leave request or an expense claim to a manager or department head. The job position supplies the expected salary context, while the department supplies the grouping used by employee statistics. Together they turn a collection of individual records into a navigable organisation chart.

Both departments and job positions are full CRUD resources exposed under the HR API surface, and like every HR entity they are scoped to the tenant organisation. Keeping them as first-class, editable reference data means an organisation can restructure — splitting a department or redefining a grade — without rewriting individual employee records one by one.

4. Leave, Holidays and Attendance

Day-to-day HR operations are handled by three cooperating features: holidays, leave, and attendance.

Holidays (HolidaysPage) are classified so the calendar reflects reality: religious, public, weekend and paid holidays are distinguished rather than lumped together, which lets leave and payroll logic reason about which days are working days.

Leave types and policies (LeaveTypesPage) define the rules of entitlement. A leave type can allow half-day booking, can be marked unpaid, and carries carry-forward rules governed by a maximum-carry-forward-days value and a days-per-year allocation. Each type also has a colour for visual identification in the UI. Leave balances are tracked per employee with carry-forward support, so unused entitlement rolls over within the configured ceiling.

Leave requests (LeaveRequestsPage) follow an approval workflow: an employee raises a request, and an approver can approve it or reject it with a rejection reason. Leave is one of the document types the central approval engine can route.

Attendance (AttendancePage) records daily entries, supports check-in and check-out, and can flag an entry as late. Attendance statuses cover present, absent, late, half-day and on-leave, so the daily record and the leave record stay reconciled. This matters because unpaid-leave and attendance data ultimately influence payroll calculation, making accurate daily capture a prerequisite for correct pay.

5. Payroll Foundations — Frequencies, Periods, Components and Structures

The core payroll engine is built from four configurable building blocks that must be in place before any pay run can execute.

Pay Frequencies (PayFrequenciesPage) define how often employees are paid, and Payroll Periods (PayrollPeriodsPage) materialise those frequencies into the concrete windows a run covers.

Salary Components (SalaryComponentsPage) are the individual earnings and deductions — the named pieces that add up to gross and net pay. Salary Structures (SalaryStructuresPage) assemble components into an assignable package. A structure can enforce minimum and maximum bounds on its values, constraining what a given assignment may pay.

Importantly, the engine has a defined fallback: when an employee has no salary structure assigned, the system uses a monthly base salary instead. This means payroll can still run for employees who have not yet been placed on a formal structure, rather than failing outright, while structured employees get the richer component-level treatment.

These foundations are deliberately separated from the run itself. Because components and structures are reusable reference data, an organisation defines its compensation model once and then applies it across many periods and many employees. Salary templates extend this further: templates can be listed and applied, letting an organisation stamp a standard structure onto employees quickly. The same component and structure data later feeds the country-specific statutory previews, which read earnings in order to compute tax and social-insurance figures.

6. Payroll Runs, Payslips and Payment Details

A payroll run is where the foundations come together into actual pay. Runs are managed through PayrollRunsPage and PayrollRunDetailPage, and they follow a clear two-stage lifecycle: draft, then posted.

While a run is in draft, its figures can be reviewed and corrected. Posting the run is the committing action — and critically, posting generates a journal entry, wiring payroll directly into the accounting ledger. This is the integration point that keeps the general ledger in step with payroll liabilities and expense, so that salaries recognised in HR appear as balanced accounting entries without a separate manual journal.

Each run produces payslips (PayslipsPage), and payslips carry year-to-date totals, giving both the organisation and the employee a running cumulative view across the tax year rather than only a single period's figures.

Payment is driven by the bank and payment details held on the employee record, which include an IBAN and a SWIFT code, so that international salary payments carry the routing information banks require.

Finally, the core engine exposes a Statutory Forms hub (StatutoryFormsPage). This hub is the entry point from which the country-specific compliance engines are driven, connecting the generic draft-to-posted payroll run to the jurisdiction-specific filing and certificate generation covered in the country payroll topic.