10 — HR & Payroll
CEO Summary
HR system with employees, timeclock (clock in/out), timesheets, payroll runs, and an Employee Portal for self-service (pay stubs, tax forms, direct deposit). Data in dev-hr-{slug} DB. Business value: Compliance, labor cost visibility, employee self-service. Key metrics: Payroll accuracy, time-off balance. If this breaks: Payroll cannot run; employees cannot clock in/out or access portal.
Overview
HR system. Data in dev-hr-{slug} DB. Two entry points: Admin (staff dashboard) and Employee Portal (employee self-service).
Timeclock
| Route | Purpose |
|---|---|
| POST /api/hr/timeclock/clock-in | Clock in |
| POST /api/hr/timeclock/clock-out | Clock out |
| POST /api/hr/timeclock/break-start | Start break |
| POST /api/hr/timeclock/break-end | End break |
| POST /api/tenant-time/punch | Toggle clock in/out (staff) |
| GET /api/tenant-time/status | Current clock status |
| GET /api/tenant-time/roster | Team roster with clock status (managers) |
| POST /api/tenant-time/clock-out-staff/:staffId | Manager clock out staff |
| GET /api/tenant-time/timesheet/:staffId | Timesheet for staff |
Data: Timesheets table — staff_id, clock_in_at, clock_out_at, status
Employee Portal
URL: /employee-portal or /employee-portal/:orgSlug (e.g. /employee-portal/mariospizza)
Route file: backend/routes/hr/employeePortal.routes.js
Auth: Employee number + credential (PIN). Session cookie: employee_session.
| Endpoint | Purpose |
|---|---|
| POST /api/employee-portal/login | Authenticate (identifier, credential) |
| POST /api/employee-portal/logout | Logout |
| GET /api/employee-portal/me | Current employee info |
| PUT /api/employee-portal/me | Update email, phone, address, emergency contact |
| GET /api/employee-portal/pay-stubs | Pay stubs (year, limit, offset) |
| GET /api/employee-portal/pay-stubs/:id | Single pay stub |
| GET /api/employee-portal/tax-forms | W-2/1099 (year) |
| POST /api/employee-portal/change-work-password | Change work password |
| POST /api/employee-portal/change-portal-pin | Change portal PIN (4 digits) |
| GET /api/employee-portal/bank-accounts | Direct deposit accounts |
| POST /api/employee-portal/bank-accounts | Add bank account |
| PUT /api/employee-portal/bank-accounts/:id | Update bank account |
| DELETE /api/employee-portal/bank-accounts/:id | Delete bank account |
Services: employeePortal.service.js, directDeposit.service.js
Admin HR Routes
hr.routes, payroll, time, tenantTime, teamHours, staff, hr/security
HR sub-routes: hr/employees, hr/departments, hr/benefits, hr/timeOff, hr/reports, hr/payrollRunManager, hr/payrollRuns, hr/payrollCalculation, hr/taxRates, hr/businessTaxInfo
Key Tables
business_tax_info, employees, employee_w4, employee_compensation, pay_periods, payroll_runs, payroll_line_items, time_off_requests, pto_balances, departments, benefit_plans
Employee Routing
tenantEmployeeRouting.service — tenant_employees (master) → route to correct tenant HR DB.