Introduction

Zeri HR is a complete HR management system built for managing employee records, attendance, leave, payroll, notices, approvals, teams, projects and role-based access control.

The system is designed for companies that need a structured HR workflow with permission-based visibility. Each user sees only the modules and records allowed by their assigned role permissions.

System Requirements

Installation

Local Setup

1. Place the project folder inside the web root, for example htdocs/hr-payroll.
2. Create a MySQL database.
3. Copy .env.example to .env and configure database credentials.
4. Install dependencies with Composer.
5. Run migrations and the default admin seeder.
6. Open the application in the browser.

composer install
php artisan key:generate
php artisan migrate
php artisan db:seed --class=AdminUserSeeder

Important Storage Commands

php artisan storage:link
php artisan optimize:clear

Default Seed Data

Zeri HR includes a single default admin seeder for fresh installations. It creates all permissions, default organization roles, role-permission assignments and one active admin user.

Seed Command

php artisan db:seed --class=AdminUserSeeder

Run this command after migrations. Admin or HR users can adjust the default roles and permissions later from the Roles screen based on company policy.

Default Admin Login

Default Admin Environment Variables

The default admin user can be changed before seeding by editing the following values in .env:

DEFAULT_ADMIN_NAME="System Admin"
DEFAULT_ADMIN_EMAIL=admin@zerihr.local
DEFAULT_ADMIN_PASSWORD=password

Permissions Seed

The default admin seeder creates all system permissions, creates organization role templates, syncs each role with a practical permission set and creates the default admin user.

Single Default Seed Command

php artisan db:seed --class=AdminUserSeeder

Use this command when you need the default permissions, role templates, role-permission assignments and one admin user with full access.

Refresh Role Permissions Only

php artisan db:seed --class=RolePermissionSeeder

This command recreates missing permissions if needed, creates the same default role templates and syncs the default role-permission assignments without creating the default admin user.

Default Organization Roles

Payroll Permission Update Commands

After adding or updating payroll, loan, bonus and permission-scope features, run these commands to update the database, refresh the default role mappings and clear cached files.

php artisan migrate
php artisan db:seed --class=AdminUserSeeder
php artisan view:cache
php artisan optimize:clear

• Dashboard permissions.
• Employee and profile update permissions.
• Attendance permissions.
• Leave permissions.
• Payroll, salary, loan, deduction, provident fund and payslip permissions.
• Announcement permissions.
• Team, project and task permissions.
• User, role and permission management permissions.
• Settings and report permissions.

Verified Permission Scope Examples

First Admin Setup After Login

After installation and AdminUserSeeder, login with the default admin account and complete the system setup before allowing employee or manager access.

Recommended Setup Order

1. Change the default admin password from the dashboard password screen.
2. Open Settings and update company profile, logo, favicon, contact information, timezone, currency and email settings.
3. Create core organization records: departments, designations and reporting structure.
4. Create salary grades with salary ranges and band names.
5. Review default roles and permissions. Keep Admin/Super Admin full access, then adjust HR Admin, Department Head, Payroll Manager, Finance Manager and Employee roles based on company policy.
6. Create or approve user accounts only after the employee profile is created and linked to the user account.
7. Create employee profiles with department, designation, manager/reporting line, salary grade, employment status and linked user account.
8. Configure leave categories, leave policies, holidays and attendance rules before employees start applying for leave or clocking attendance.
9. Create payroll setup records: salary templates, employee salary assignments, provident fund setup, recurring deductions and opening loan records if needed.
10. Run a small test payroll draft for one employee and review salary, deduction, loan, PF, tax and net payable before processing a full payroll run.

Setup Checklist

User Approval Rule

Registered users stay in pending_approval. Admin must create or link the employee profile first, then approve the user and assign the correct role. Approval is blocked when the user has no linked employee profile.

Login and Access

Users access the system through the login page using their approved account email and password.

Login Flow

1. Open the application URL.
2. Enter email and password.
3. After login, the system redirects the user to the dashboard.

Access Control

Access is controlled by role permissions. A user can only view modules and perform actions allowed by their assigned role.

Demo User Login

For demo environments, run the demo user seeder to create four ready-to-use accounts. The login page shows these demo users with copy buttons.

php artisan db:seed --class=DemoUserSeeder

Employee Login Setup

Creating an employee profile does not automatically create login access. Login access comes from the user account, and the employee profile must be linked to that user account.

Required Workflow

1. Go to User Management > Add User.
2. Create a user with name, email, password and role.
3. Use the Employee role for normal employee access, or assign another role based on your permission setup.
4. Approve or activate the user account if approval is enabled.
5. Go to Employees > Employee List.
6. Edit the employee profile.
7. In the User Account field, select the user account created earlier.
8. Save the employee profile.
9. The employee can now log in using the linked user email and password.

How It Works Internally

Navigation

The left sidebar contains all available modules. Menu visibility depends on the logged-in user's permissions.

• Dashboard: Summary of employee, attendance, leave, notices and quick notes.
• Employees: Employee records, departments, designations and approvals.
• Attendance: Attendance logs and attendance integration tools.
• Leave Management: Leave applications, balances, approvals and policies.
• Payroll: Salary setup, bonuses, loans, deductions, provident fund and payroll runs.
• User Management: Users, roles and permissions.
• Settings: Company and branding configuration.

Dashboard

The dashboard gives users a quick overview of HR activity based on their permissions.

Main Features

• Employee summary cards.
• Attendance summary: present, absent, late and leave.
• Pending leave request summary.
• Upcoming holidays and birthdays.
• Notice board.
• Private quick notes.
• Basic alerts.

Permission-Based Visibility

Employees

The Employees module stores employee personal, official, contact and employment information.

Employee List

• Search employees by code, name, phone or email.
• Filter employees by department, designation, status and employment type.
• View employee profile details.
• Edit employee information when permission is granted.

Add / Edit Employee

• Upload employee profile picture.
• Assign user account.
• Set department, designation, salary grade and manager.
• Record joining date, employment type and employment status.
• Store addresses, bank accounts, emergency contacts and documents.

Employee Related Tables

Profile Update Requests

Employees can submit profile update requests instead of directly changing official records. HR reviews the request and approves or rejects it.

Employee Workflow

1. Employee opens the profile update page.
2. Employee changes personal information, contact details or profile image.
3. Employee submits the request for HR approval.

HR Workflow

1. HR opens the update approval queue.
2. HR compares current and requested information.
3. HR approves or rejects the request.
4. On approval, employee data is updated.

Organization Structure

The organization structure page displays reporting relationships and hierarchy.

Departments

• Create departments with department code and description.
• Assign department head.
• Activate or deactivate departments.

Designations

• Create job titles/designations.
• Assign designations to employees.
• Use designations for employee filtering and reports.

Attendance

The Attendance module tracks employee check-in, checkout, attendance status and attendance reports.

Features

• View attendance logs.
• Clock attendance when permitted.
• Manage attendance records.
• Import attendance data.
• Export attendance report.
• API integration support for attendance devices or external systems.

Attendance Status

Leave Management

The Leave Management module handles leave categories, leave policies, leave balances, employee applications, approvals and reports.

Leave Categories

Create categories such as Casual Leave, Sick Leave, Annual Leave or Earned Leave.

Leave Policies

• Assign leave rules by salary grade.
• Set yearly allocation.
• Configure carry forward and earned leave rules.
• Activate/deactivate policies.

Recommended Sick, Casual and Annual Leave Setup

Earned and Carry Forward Rules

• Sick Leave: use yearly allocation, Carry Forward Mode = None, Earned Leave = No, Earned Credit Days = 0.
• Casual Leave: use yearly allocation, Carry Forward Mode = None, Earned Leave = No, Earned Credit Days = 0.
• Annual Leave: use yearly allocation, Carry Forward Mode = Full or Limited, Earned Leave = Yes, Earned Credit Frequency = Monthly.
• For monthly earned annual leave, set Earned Credit Days to yearly annual leave allocation divided by 12. Example: 14 annual days / 12 = 1.17 days per month.
• At year start, sick and casual leave balances reset to the new year allocation. Only annual leave receives carry-forward balance.

Year-End Example

Leave Balances

• Sync leave balances by year.
• Filter balances by employee, grade or leave category.
• Adjust leave balances where permitted.

Automatic Monthly Leave Balance Sync

The system includes a scheduled leave balance sync command. It recalculates the current year leave balance for active employees, including monthly earned leave credits, so HR does not need to press the Sync button every month.

• Scheduled command: php artisan leave:sync-balances.
• Default schedule: last day of every month at 23:50 server time.
• The sync is safe to rerun because balances are recalculated and updated for the year; it does not blindly add the same monthly earned leave again.
• Manual full-year sync: php artisan leave:sync-balances 2026.
• Manual sync for one salary grade: php artisan leave:sync-balances 2026 --salary_grade_id=3.
• Manual sync for one employee: php artisan leave:sync-balances 2026 --employee_id=25.

Add this cron entry on the server so Laravel can run scheduled jobs:

* * * * * cd /Applications/XAMPP/xamppfiles/htdocs/hr-payroll && php artisan schedule:run >> /dev/null 2>&1

If the project path is different on production, replace the path with the production project directory.

Leave Applications and Approvals

1. Employee submits leave application.
2. Approver reviews pending leave.
3. Approver approves or rejects the application.
4. Reports can be exported for HR review.

Notices and Announcements

Announcements let HR or Admin publish company notices to selected audiences.

Features

• Create notices with title and body.
• Set announcement type and priority.
• Select audience: all users, departments or selected employees.
• Publish or approve announcements based on permissions.
• Show notices on dashboard and topbar notifications.

Teams, Projects and Tasks

Work management modules help organize teams, projects and task assignments.

Teams

• Create team records.
• Assign team members.
• Manage team visibility by permissions.

Projects

• Create projects with project code and details.
• Assign members to projects.
• View project details and related tasks.

Tasks

• Create task with title, priority and status.
• Assign task to employee.
• Track start date, due date, progress and hours.
• Add task comments when permitted.

Payroll Overview

The Payroll module manages salary structure, employee-specific salary assignment, bonuses, loans, deductions, provident fund and payslip generation.

Payroll Flow

1. Create Salary Grades.
2. Create reusable Salary Templates.
3. Assign Employee Salary from a salary template and customize the actual employee salary values.
4. Add bonuses, loans, deductions and provident fund settings.
5. Generate Payroll Draft for selected period. Draft shows expected salary, bonus, loan installment deduction, other deductions, PF, tax and net payable.
6. Review all payroll items and payslips before final submission.
7. Final Submit payroll run. This is the posting step for salary-linked records such as loan installment payment and PF contribution.
8. Mark individual payslips as paid after payment processing.

Payroll Run Generation Logic

Salary Grades

Salary Grade represents employee level and salary range. It is not the final salary amount for every employee.

Example

Usage

• Classifies employees by level.
• Provides allowed salary range.
• Used by leave policies and HR reports.
• Used to validate employee salary assignment amounts.

Salary Templates

Salary Template is a reusable default salary structure. It helps HR quickly assign salary structure, but final employee salary is stored separately as an employee-specific snapshot.

Template Fields

• Basic salary.
• House rent.
• Medical allowance.
• Conveyance allowance.
• Other allowance.
• Provident fund percentage.
• Tax percentage.

Employee Salary Assignment

This is the final salary setup used during payroll calculation. Employees in the same salary grade can have different salary amounts.

How It Works

1. Select employee.
2. Select salary structure/template.
3. The system fills default template values.
4. HR customizes the salary values for that employee.
5. Save assignment with effective dates.

Assignment Rules

• Basic salary must be within the employee salary grade min/max range when configured.
• Overlapping salary assignment date ranges are blocked.
• Assigning a new active salary closes the previous active assignment automatically.
• Payroll requires an active salary assignment for the payroll period.

Stored Snapshot Values

Bonuses

Bonus records are added for employees and included in payroll when the bonus date falls within the payroll period.

Fields

• Employee.
• Title.
• Amount.
• Bonus date.
• Bonus type.
• Remarks.

Employee Loans

The Loan module tracks employee loan requests, approval status, installment schedules and salary-based repayment.

Loan Master

• Employee.
• Loan reference.
• Principal Amount.
• Interest percentage.
• Installment count.
• Installment Amount, calculated from Principal Amount, Interest % and Installment Count.
• Issued date and first installment date.
• Status: pending supervisor, pending final, active, paused, closed or rejected.

Installment Amount Formula

The user enters Principal Amount, optional Interest % and Installment Count. The application calculates Installment Amount automatically in the form and recalculates it again on the backend when saving or rescheduling.

total_payable = principal_amount + (principal_amount * interest_percent / 100)
installment_amount = total_payable / installment_count

Loan Approval Flow

1. Employee submits a loan request with loan.apply or employee_loan.apply.
2. Supervisor or department approver reviews team requests with loan.approve-supervisor or employee_loan.approve-supervisor.
3. Final approver completes approval with loan.approve-final or employee_loan.approve-final.
4. After final approval, the loan becomes active and installment schedules are generated.
5. Rejected loans are stored with rejection information and are not deducted from payroll.

Loan Installments

Installments are created from the approved loan schedule. Payroll picks pending installments when their due date falls inside the payroll period.

Installment due dates are generated monthly from the first installment date. If first installment date is empty, the issued date is used as the first due date.

Salary Deduction Workflow

1. Loan must be active before it can be deducted from payroll.
2. Payroll draft calculates loan_deduction from pending installments due inside the payroll period.
3. HR reviews the draft payslip and confirms that the loan deduction is correct.
4. When HR final submits the payroll run, those due installments are marked as paid.
5. The paid installment stores the payroll item reference so HR can see which salary/payslip paid it.
6. When all installments are paid, the loan status becomes closed automatically.

Reschedule Rules

• Reschedule is allowed only when no installment has been paid.
• Reschedule recalculates Installment Amount from Principal Amount, Interest % and Installment Count.
• The old pending schedule is deleted and a new schedule is created.
• Reschedule is blocked after any installment is paid to protect payroll history.

Manual Installment Payment

Manual installment payment should be used only for payments collected outside salary, such as cash, bank deposit or adjustment. Salary-related repayment should normally happen through payroll finalization.

Deductions

Deductions are employee-specific amounts deducted during payroll calculation. General deductions and loan deductions are handled separately so loan balances remain accurate.

Supported Deduction Setup

• Deduction name, such as welfare fund, penalty or advance adjustment.
• Calculation method: Fixed Amount or Percent of Basic Salary.
• Amount / Percent value.
• Effective from and effective to.
• Deduction frequency: Every Monthly Payroll, Every Weekly Payroll or One Payroll Only.
• Reason / policy and internal notes.
• Active/inactive status.

How Deduction Calculation Works

During payroll draft generation, matched deductions are copied into the payslip deduction breakdown and summed into other_deduction. The amount then becomes part of total_deduction and reduces net payable.

Provident Fund

Provident Fund setup defines employee contribution percentage, employer contribution percentage, opening balance and effective date.

How PF Works

• Employee PF % is deducted from employee basic salary and reduces net payable.
• Employer PF % is company contribution and does not reduce employee net payable.
• Both contributions are calculated from the active basic salary for the payroll period.
• If salary increases through a new employee salary assignment, future payroll runs automatically calculate higher PF amounts.
• PF setup is used when its effective date is empty or before the payroll period end date. If no PF setup is active, payroll falls back to the employee salary assignment PF percentage.
• During final payroll submission, PF contribution transactions are posted with employee contribution, employer contribution and balance after.
• PF transactions can be used for yearly self-service and HR reports.

Example

PF Report

• Report route: /reports/provident-fund.
• Export route: /reports/provident-fund/export.
• Employees can view their own yearly PF report when provident_fund.view is assigned.
• HR, Admin, Payroll or Finance users with provident_fund.report or payroll.manage-pf can filter by year, department and employee.
• CSV export is available to users with report.export, provident_fund.report or payroll.manage-pf.
• The report shows employee contribution, employer contribution, withdrawals, adjustments and balance after each transaction.

Payroll Runs

Payroll run is the monthly or weekly payroll batch for one period.

Draft and Final Submission Flow

1. HR generates payroll draft for a period.
2. The system creates payroll items for employees.
3. HR reviews every payroll item and payslip.
4. If needed, HR adjusts employee salary assignment, bonus, loan, deduction or PF setup.
5. HR regenerates draft for the same period.
6. When everything is correct, HR clicks Final Submit.
7. The run becomes processed, PF transactions are posted and due loan installments are marked paid against their payslips.

Payroll Calculation

Gross = basic_salary + allowance_total + bonus_total
Total Deduction = loan_deduction + other_deduction + provident_fund_deduction + tax_deduction
Net Payable = Gross - Total Deduction

Final Submit Posting Rules

• Payroll draft can be regenerated before final submission.
• Final submission locks the payroll run as processed.
• Due pending loan installments in the payroll period are marked paid and linked to the employee payslip.
• If due loan installment amounts changed after draft generation, the system blocks final submission and asks HR to regenerate the draft.
• Provident fund contribution transactions are posted for the run.
• After final submission, payslips can be marked as paid when salary payment is completed.

Important Status Meaning

Payslips

Each payroll item works as an employee payslip inside the payroll run.

Payslip Contains

• Employee information.
• Payroll period.
• Basic salary.
• Allowance total.
• Bonus total.
• Loan deduction.
• Other deductions.
• Provident fund deduction.
• Tax deduction.
• Net payable.

Payment Status

Payment can be marked as paid only after the payroll run is finalized. Loan deduction on the payslip is already posted to loan installments at payroll final submission; marking payslip payment as paid records the salary payment status.

Loan Deduction Trace

When a payslip deducts loan installment amount, the loan installment stores the payroll item reference. The loan installment list shows whether the installment was paid by payroll or manually.

Salary Revisions

Salary revision history records salary changes, effective dates and approval information.

Usage

• Track promotion-related salary changes.
• Record previous and revised salary.
• Store approval information.
• Maintain history for HR audit.

Holidays

The Holidays module stores official holidays and helps dashboard/event widgets show upcoming holidays.

Features

• Create holidays with name and date.
• Edit holiday information.
• Delete holiday records.
• Export current-year holiday list.

Users, Roles and Permissions

User Management controls who can access the system and what each user can do.

Users

• Create user accounts.
• Approve or reject user access.
• Assign users to roles.
• Link users with employee records.

Roles

• The default seed creates common organization roles with practical permission assignments.
• Super Admin and Admin receive all permissions by default.
• HR Admin, HR Manager, Payroll Manager, Finance Manager, Department Head, Supervisor, Project Manager, Team Lead, Auditor and Employee receive scoped default permissions.
• Admin or HR users can change the assigned permissions later from the Roles screen.
• Users inherit access from assigned roles.

Permissions

Permissions are grouped by module, for example employee.view, payroll_run.generate, payslip.view and settings.update.

Permission access labels are database driven. Each permission stores an access scope key, label, badge class and description, so the role permission screen can show whether a permission is for own access, department/team access, admin/global access or general access.

Data Access Rules

• Employee self-service: Employees can view their own attendance, leave applications, leave balances, assigned teams, assigned projects, assigned tasks, payslips, loans, deductions and provident fund records when the related view permission is assigned.
• Supervisor access: Supervisors can view their own records and direct subordinate records for attendance, leave approval/reporting and task work scope. Supervisor access does not automatically expose payroll finance records.
• Payroll privacy: Salary, payslip, loan, deduction and provident fund records are self-only unless payroll management or payroll report permissions are assigned.
• Work module access: Team, project and task lists are scoped to records where the user is a lead, manager, member, assignee, creator or direct supervisor of an assignee. Management permissions allow wider setup access.
• Holiday access: Users with holiday view permission can see the holiday list/calendar. Create, update and delete actions require separate holiday permissions.

Payroll Permission Meaning

Payroll, loan, deduction and payslip data are confidential. Department Head, Supervisor, Project Manager and Team Lead roles should not receive global payroll permissions unless the company intentionally allows them to see salary records.

Recommended Role Assignment

Role-Based Permission Matrix

Use this matrix as a practical starting point when creating or reviewing roles. The default seed already assigns similar permissions, but every company should adjust sensitive payroll, finance and settings access based on internal policy.

Permission Assignment Rules

• Assign one primary job role per user where possible. Do not add Employee role to HR Admin, Payroll Manager or Department Head if their role already includes self-service permissions.
• Every staff login should be linked to an employee profile before approval, including HR Admin, Department Head, CEO/Managing Director and Payroll users.
• Give payroll and payslip report permissions deliberately. Generic report access should not automatically mean salary access.
• Use role.assign only for trusted administrators who can change user access.
• Use settings.update only for users allowed to change company-wide configuration.
• Use payroll_run.approve only for the person authorized to final submit payroll.

User Approval and Employee Setup

1. New registered users remain in pending_approval.
2. Admin must create or link the employee profile before approval.
3. The employee profile stores staff identity, department, designation, reporting line, attendance scope, leave scope and payroll identity.
4. After employee setup is complete, admin can approve the user and assign the correct role such as Employee, HR Admin, Department Head or Payroll Manager.
5. Approval is blocked when no employee profile is linked to the user.

Role-Based Operation Guide

This guide explains what each common role should normally do in the system. The final behavior still depends on the permissions assigned to the role from the database.

Employee Lifecycle by Role

Module-Wise Permission Meaning

Settings

The Settings module manages company profile, branding and application configuration.

Typical Settings

• Company name.
• Logo and branding images.
• Contact information.
• System preferences.

Localization

Zeri HR supports multilingual UI labels for dashboard, employees, departments, designations, attendance, leave, payroll, users, roles, permissions, holidays, notices, teams, projects, settings and reports.

Supported Languages

How Language Selection Works

• Users can change the interface language from the topbar language selector.
• The selected language is stored in the session and applied through the locale middleware.
• Translation files are stored in lang/en.json, lang/de.json, lang/fr.json and lang/hi.json.
• Database content such as employee names, department names, project names and notice titles remains user-entered content and is not automatically translated.

Reports

Reports help HR and management export or review operational records.

Available Report Areas

• Attendance reports.
• Leave reports.
• Payroll reports.
• Employee reports.
• Provident fund reports.

Notifications

Topbar notifications show relevant alerts to the logged-in user.

Examples

• Announcements and notices.
• Pending leave requests.
• Attendance alerts.
• Upcoming holidays.
• Task-related notifications.

Notification visibility is permission and scope based. Admin-level users can see wider alerts; employees see their own relevant alerts.

FAQ

Can employees in the same salary grade have different salaries?

Yes. Salary Grade defines the allowed range. Employee Salary Assignment stores the actual employee-specific salary snapshot.

Does payroll use the shared salary template directly?

No. Payroll uses the employee-specific salary snapshot stored in employee_salary_templates.

Can HR review payroll before final submission?

Yes. Payroll generation creates a draft run. HR reviews the run and final submits only after checking.

Can payment be marked before payroll final submission?

No. Payslip payment can be marked only after the payroll run is finalized.

How is loan installment amount calculated?

The system calculates it from Principal Amount, Interest % and Installment Count: (principal + interest amount) / installment count. The backend recalculates it during save and reschedule.

Can a loan be rescheduled after payroll paid an installment?

No. Rescheduling is blocked after any installment is paid so payroll and loan history remain consistent.

Why can some users not see a module?

The user role may not have the required permission. Assign the needed permission from Role Permissions.

Screenshot Guide

All screenshot placeholders in this document point to the following folder:

Documentation/assets/screenshots/

Recommended image naming:

• dashboard.png
• employees-list.png
• attendance-list.png
• leave-management.png
• salary-templates.png
• employee-salary-assignment.png
• payroll-runs.png
• payroll-run-detail.png
• payslip-detail.png