Processing Payroll

Overview

The Payroll module in HCMatrix streamlines compensation management, salary processing, and payroll reporting. This comprehensive system integrates with employee records and attendance data to ensure accurate payroll processing.

Accessing Payroll

Navigate to Payroll Module

Access the Payroll section from the main navigation sidebar. The system verifies your authentication status:

// From: ~/workspace/source/app/payroll/page.tsx:12-16
useEffect(() => {
  if (!auth.getToken()) {
    router.push('/auth/login')
  }
}, [router])

Authentication Validation

Only authenticated users with valid tokens can access payroll data. Unauthorized users are automatically redirected to the login page.

Current Implementation

The payroll module uses the standard HCMatrix layout architecture:

// From: ~/workspace/source/app/payroll/page.tsx:18-31
return (
  <div className="min-h-screen bg-gray-50">
    <Sidebar />
    <div className="ml-64 flex flex-col min-h-screen">
      <Header title="Payroll" />
      <main className="flex-1 p-8">
        <div className="bg-white rounded-lg border border-gray-200 p-8 text-center">
          <p className="text-gray-600">Payroll module coming soon...</p>
        </div>
      </main>
    </div>
  </div>
)

The Payroll module is under active development. Advanced payroll processing features, tax calculations, and reporting capabilities are being built.

Planned Features

The upcoming Payroll module will provide comprehensive compensation management:

Salary Management

Employee salary records and history
Compensation adjustments and raises
Bonus and commission tracking
Multi-currency support

Payroll Processing

Automated payroll runs
Pay period configuration (weekly, bi-weekly, monthly)
Overtime calculations
Deduction management

Tax & Compliance

Automatic tax calculations
Tax withholding management
Compliance with local regulations
Year-end tax reporting (W-2, 1099, etc.)

Payment Methods

Direct deposit setup
Check printing
Payment history tracking
Failed payment handling

Employee Compensation Data

Employee salary information is already tracked in the employee detail records:

// From: ~/workspace/source/lib/api.ts:49-62
export interface EmployeeDetail extends Employee {
  phone: string
  date_of_birth: string
  address: string
  salary: number  // Current employee salary
  manager: string
  manager_id: number
  next_of_kin_name: string
  next_of_kin_relationship: string
  next_of_kin_phone: string
  tenure_years: number
  tenure_months: number
  spouse: string | null
}

Accessing Salary Information

// From: ~/workspace/source/lib/api.ts:129-145
function mapEmployeeDetail(raw: any): EmployeeDetail {
  return {
    ...mapEmployee(raw),
    phone: raw.phone || raw.phone_number || '',
    date_of_birth: raw.dob || raw.date_of_birth || '',
    address: raw.address || '',
    salary: raw.current_salary ?? raw.salary ?? 0,  // Salary mapping
    manager: raw.manager || '',
    manager_id: raw.manager_id || 0,
    next_of_kin_name: raw.next_of_kin || raw.next_of_kin_name || '',
    next_of_kin_relationship: raw.next_of_kin_relationship || raw.relationship || '',
    next_of_kin_phone: raw.phone_no_nok || raw.next_of_kin_phone || '',
    tenure_years: raw.tenure_years ?? 0,
    tenure_months: raw.tenure_months ?? 0,
    spouse: raw.spouse || null,
  }
}

Integration with Other Modules

Payroll integrates with multiple HCMatrix systems:

Employee Management

Pull salary data from employee records
Update compensation history
Track employment status changes
Link payroll to employee profiles

Attendance Tracking

Import hours worked from time cards
Calculate overtime automatically
Process PTO and leave balances
Verify attendance for payroll accuracy

Reporting

Generate payroll summaries
Export tax reports
Analyze compensation trends
Audit payroll history

Planned API Structure

The payroll API will follow HCMatrix conventions:

// Example future API endpoints
export const api = {
  // Run payroll for a pay period
  async runPayroll(
    token: string,
    startDate: string,
    endDate: string
  ): Promise<PayrollRun> {
    return apiCall<PayrollRun>('/api/v1/payroll/run', 'POST',
      { start_date: startDate, end_date: endDate },
      token
    )
  },

  // Get payroll records for an employee
  async getEmployeePayroll(
    token: string,
    employeeId: number,
    year?: number
  ): Promise<PayrollRecord[]> {
    const params = year ? { employee_id: employeeId, year } : { employee_id: employeeId }
    const queryString = new URLSearchParams(params as any).toString()
    return apiCall<PayrollRecord[]>(
      `/api/v1/payroll/employee?${queryString}`,
      'GET',
      undefined,
      token
    )
  },

  // Update employee compensation
  async updateSalary(
    token: string,
    employeeId: number,
    newSalary: number,
    effectiveDate: string
  ): Promise<SalaryUpdate> {
    return apiCall<SalaryUpdate>(
      `/api/v1/payroll/salary/${employeeId}`,
      'POST',
      { salary: newSalary, effective_date: effectiveDate },
      token
    )
  },

  // Process direct deposit
  async processDirectDeposit(
    token: string,
    payrollRunId: number
  ): Promise<PaymentResult> {
    return apiCall<PaymentResult>(
      `/api/v1/payroll/direct-deposit/${payrollRunId}`,
      'POST',
      {},
      token
    )
  }
}

Data Structures

Planned payroll data interfaces:

export interface PayrollRun {
  id: number
  start_date: string
  end_date: string
  status: 'draft' | 'processing' | 'completed' | 'failed'
  total_gross: number
  total_deductions: number
  total_net: number
  employee_count: number
  created_at: string
  processed_at?: string
}

export interface PayrollRecord {
  id: number
  employee_id: number
  payroll_run_id: number
  gross_pay: number
  deductions: Deduction[]
  net_pay: number
  payment_method: 'direct_deposit' | 'check'
  payment_status: 'pending' | 'paid' | 'failed'
  pay_date: string
}

export interface Deduction {
  type: 'tax' | 'insurance' | 'retirement' | 'garnishment' | 'other'
  description: string
  amount: number
  is_percentage: boolean
}

export interface SalaryUpdate {
  employee_id: number
  previous_salary: number
  new_salary: number
  effective_date: string
  reason?: string
  approved_by?: number
}

export interface PaymentResult {
  payroll_run_id: number
  total_payments: number
  successful: number
  failed: number
  pending: number
  errors?: PaymentError[]
}

export interface PaymentError {
  employee_id: number
  employee_name: string
  error_message: string
}

Security & Compliance

Payroll data is highly sensitive and requires strict security:

All payroll operations require authentication tokens. Access to compensation data should be restricted to authorized HR personnel and system administrators only.

Best Practices

Data Encryption: All salary and payment information is encrypted
Access Control: Role-based permissions limit who can view/edit payroll
Audit Trails: All payroll changes are logged with user and timestamp
Compliance: System adheres to labor laws and tax regulations
Backup: Payroll data is backed up before each processing run

Payroll Processing Workflow

When the module launches, follow this workflow:

Collect Time Data

Import attendance and hours worked from the Time & Attendance module

Verify Employee Data

Ensure all employee records are up-to-date with current salaries and deductions

Run Payroll Calculation

Execute the payroll run for the pay period, calculating gross pay, taxes, and deductions

Review & Approve

Review payroll summary for accuracy and get manager approval

Process Payments

Submit direct deposits or generate checks for employees

Generate Reports

Create payroll reports for accounting, tax filing, and record-keeping

Schedule payroll processing 2-3 days before pay date to account for bank processing times and allow for error correction.

Next Steps

Managing Employees - Update employee compensation
Tracking Attendance - Import time cards
Generating Reports - Create payroll reports
Authentication Guide - Secure access to payroll data

Getting Started

Core Features

User Guide

Configuration

Processing Payroll

Overview

Accessing Payroll

Current Implementation

Planned Features

Salary Management

Payroll Processing

Tax & Compliance

Payment Methods

Employee Compensation Data

Accessing Salary Information

Integration with Other Modules

Employee Management

Attendance Tracking

Reporting

Planned API Structure

Data Structures

Security & Compliance

Best Practices

Payroll Processing Workflow

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Features

User Guide

Configuration

Documentation Index

​Overview

​Accessing Payroll

​Current Implementation

​Planned Features

​Salary Management

​Payroll Processing

​Tax & Compliance

​Payment Methods

​Employee Compensation Data

​Accessing Salary Information

​Integration with Other Modules

​Employee Management

​Attendance Tracking

​Reporting

​Planned API Structure

​Data Structures

​Security & Compliance

​Best Practices

​Payroll Processing Workflow

​Next Steps

Build docs developers (and LLMs) love

Overview

Accessing Payroll

Current Implementation

Planned Features

Salary Management

Payroll Processing

Tax & Compliance

Payment Methods

Employee Compensation Data

Accessing Salary Information

Integration with Other Modules

Employee Management

Attendance Tracking

Reporting

Planned API Structure

Data Structures

Security & Compliance

Best Practices

Payroll Processing Workflow

Next Steps