payroll-designer

id: hr-payroll-designer
name: Payroll System Designer
tier: 2
domain: hr-management
triggers:
  - payroll
  - compensation
  - salary
  - wage calculation
capabilities:
  - Payroll processing workflows
  - Tax calculation integration
  - Benefits deductions
  - Compliance reporting

Payroll System Designer

Role

Specialist in designing payroll processing systems including wage calculation, tax withholding, benefits deductions, and compliance reporting.

Expertise Areas

Payroll Processing

• Pay period management
• Gross pay calculation
• Tax withholding
• Net pay calculation

Compensation Management

• Salary structures
• Hourly/salary pay types
• Overtime calculation
• Bonus and commission

Deductions & Benefits

• Pre-tax deductions
• Post-tax deductions
• Benefits enrollment integration
• Garnishments

Compliance

• Federal tax reporting (W-2, 941)
• State tax requirements
• FLSA compliance
• Audit trails

Design Patterns

Employee Compensation Model

interface EmployeeCompensation {
  employeeId: string;

  // Pay Type
  payType: 'salary' | 'hourly' | 'commission' | 'contract';
  payFrequency: PayFrequency;

  // Base Compensation
  basePay: {
    amount: number;
    currency: string;
    effectiveDate: Date;
    annualEquivalent: number;
  };

  // Additional Compensation
  additionalPay: {
    overtime?: OvertimeConfig;
    shift_differential?: ShiftDifferential[];
    bonus?: BonusConfig;
    commission?: CommissionConfig;
  };

  // Tax Information
  taxInfo: {
    federalFilingStatus: FederalFilingStatus;
    federalAllowances: number;
    additionalFederalWithholding: number;
    stateWithholdings: StateWithholding[];
    localWithholdings: LocalWithholding[];
  };

  // Deductions
  deductions: Deduction[];

  // Direct Deposit
  directDeposit: DirectDepositAccount[];

  // History
  compensationHistory: CompensationChange[];
}

type PayFrequency = 'weekly' | 'bi_weekly' | 'semi_monthly' | 'monthly';

interface Deduction {
  id: string;
  type: DeductionType;
  name: string;
  amount: number;
  amountType: 'fixed' | 'percentage';
  preTax: boolean;
  frequency: PayFrequency;
  startDate: Date;
  endDate?: Date;
  benefitPlanId?: string;
}

type DeductionType =
  | 'health_insurance'
  | 'dental_insurance'
  | 'vision_insurance'
  | 'life_insurance'
  | '401k'
  | 'hsa'
  | 'fsa'
  | 'garnishment'
  | 'union_dues'
  | 'parking'
  | 'other';

Payroll Processing Service

interface PayrollProcessingService {
  // Payroll runs
  createPayrollRun(period: PayPeriod): Promise<PayrollRun>;
  calculatePayroll(runId: string): Promise<PayrollCalculation>;
  reviewPayroll(runId: string): Promise<PayrollReview>;
  approvePayroll(runId: string, approver: string): Promise<void>;
  processPayroll(runId: string): Promise<PayrollResult>;

  // Individual calculations
  calculateEmployeePay(employeeId: string, period: PayPeriod): Promise<PayStatement>;
  recalculateEmployee(runId: string, employeeId: string): Promise<PayStatement>;

  // Adjustments
  addAdjustment(runId: string, adjustment: PayrollAdjustment): Promise<void>;
  processOffCyclePayment(request: OffCycleRequest): Promise<PayStatement>;

  // Reporting
  generatePayrollReport(runId: string): Promise<PayrollReport>;
  generateTaxReport(period: TaxPeriod): Promise<TaxReport>;
}

interface PayrollRun {
  id: string;
  payPeriod: PayPeriod;
  status: PayrollStatus;
  employees: number;

  // Totals
  totals: {
    grossPay: number;
    netPay: number;
    employerTaxes: number;
    employeeTaxes: number;
    deductions: number;
  };

  // Dates
  checkDate: Date;
  deadlineDate: Date;
  processedAt?: Date;

  // Audit
  createdBy: string;
  approvedBy?: string;
  approvedAt?: Date;
}

type PayrollStatus =
  | 'draft'
  | 'calculating'
  | 'review'
  | 'approved'
  | 'processing'
  | 'completed'
  | 'cancelled';

Pay Calculation Engine

class PayCalculationEngine {
  async calculatePay(
    employee: EmployeeCompensation,
    period: PayPeriod,
    timeData: TimeData
  ): Promise<PayCalculation> {
    // Step 1: Calculate gross pay
    const grossPay = await this.calculateGrossPay(employee, period, timeData);

    // Step 2: Calculate pre-tax deductions
    const preTaxDeductions = await this.calculatePreTaxDeductions(
      employee, grossPay
    );

    // Step 3: Calculate taxable income
    const taxableIncome = grossPay.total - preTaxDeductions.total;

    // Step 4: Calculate taxes
    const taxes = await this.calculateTaxes(employee, taxableIncome, period);

    // Step 5: Calculate post-tax deductions
    const postTaxDeductions = await this.calculatePostTaxDeductions(
      employee, taxableIncome
    );

    // Step 6: Calculate net pay
    const netPay = taxableIncome - taxes.total - postTaxDeductions.total;

    return {
      employeeId: employee.employeeId,
      period,
      grossPay,
      preTaxDeductions,
      taxableIncome,
      taxes,
      postTaxDeductions,
      netPay,
      ytdTotals: await this.calculateYTD(employee.employeeId)
    };
  }

  private async calculateGrossPay(
    employee: EmployeeCompensation,
    period: PayPeriod,
    timeData: TimeData
  ): Promise<GrossPay> {
    const earnings: Earning[] = [];

    // Regular pay
    if (employee.payType === 'salary') {
      earnings.push({
        type: 'regular',
        hours: this.getStandardHours(employee.payFrequency),
        rate: this.calculateHourlyEquivalent(employee),
        amount: employee.basePay.amount / this.getPayPeriodsPerYear(employee.payFrequency)
      });
    } else if (employee.payType === 'hourly') {
      earnings.push({
        type: 'regular',
        hours: timeData.regularHours,
        rate: employee.basePay.amount,
        amount: timeData.regularHours * employee.basePay.amount
      });
    }

    // Overtime
    if (timeData.overtimeHours > 0 && employee.additionalPay.overtime) {
      const otRate = employee.basePay.amount * emplo