# Migration notes: Government HRIS → Philippine PrivateHRIS
**Conversion date:** 2026-10-20  
**Source:** G-HRIS Codebase v1.3 Improvements  
**Status:** Initial conversion, **not production ready**

## Architectural decision

The backend intentionally retains physical `agencies.id`, `agency_id`, `offices.id` and many original model names. Those existing foreign keys isolate tenants throughout Laravel, Flutter and React. Renaming them without rebuilding all API contracts would create data-leak and migration risk. New `agencies.organization_kind` is `government` for existing records, while newly created tenants are `private` via the new admin command. A command deliberately changes a verified tenant to private; no automatic rewrite of past payroll or employment fields occurs.

## Functional mapping

| Original government feature | Private conversion / remaining work |
| --- | --- |
| Agency, Office | Company and Department labels; original IDs remain physical storage keys |
| SG, plantilla, step increment | Removed from employee entry, list/detail navigation; nullable SG for private records; further cleanup needed in recruitment/onboarding and imported data |
| GSIS, government loans | Not applied to private payroll; historical fields preserved |
| SSS | New `sss_employee`, `sss_employer`, `ec_employer`, `total_sss`, effective-dated 2025 SSS contribution rules; review worksheet |
| PERA/AdCom, YEB/cash gift | No automatic private pay; configured company allowances remain available |
| PhilHealth, Pag-IBIG, BIR | Reused with existing published rules; require rate/source verification each period |
| 13th month | Posted-basic-pay reconciliation preview, optional disabled-by-default auto December payout computation (no standalone payout) |
| CSC leave accrual | Disabled for private tenants, private reference leave seeder; company HR must assign credits and entitlements |
| CSC Reports/ROPA/PDS/SALN/OPCR/IPCR | Hidden in main navigation and selected endpoints disabled for private companies; legacy source remains |
| Recruitment/onboarding | Existing functionality remains, but CSC scoring/appointments and document templates need private-specific replacement |
| Overtime/timekeeping | Existing implementation retained; regional wage-order, night/rest-day/holiday computations need review |
| Mobile | Branding updated; original shared API models and fields remain for compatibility |
| Multi-tenancy | Existing AgencyScope and role-based permission architecture retained |

## DB/API deltas

- Migration: `backend/database/migrations/2026_10_20_000001_private_sector_foundation.php`.
- `agencies.organization_kind` = `government` / `private`.
- Employee: `hire_date`, `probation_end_date`, `contract_end_date`, `pay_basis=monthly`, `thirteenth_month_eligible`; existing `sss_number` is now in private entry flow.
- Payroll records: `sss_employee`, `sss_employer`, `ec_employer`; run `total_sss`.
- Private SSS: `backend/app/Services/Payroll/PrivateContributionService.php`. Its 2025+ SSS MSC boundaries and rates are encoded in `backend/config/contributions.php`; company-approved contribution workflows may override and must be reviewed.
- New private exports: `GET /api/v1/admin/payroll/run/{id}/export/sss` and private register variant. SSS file **is not the statutory electronic upload specification**.
- Benefit preview: `GET /api/v1/admin/payroll/13th-month/preview/{year}` (authorized payroll roles, organization-scoped, posted-only).
- Command: `php artisan privatehris:create-admin` for new companies; `php artisan privatehris:convert-company COMPANY_CODE --confirm` for cutover.

## Payroll and leave caveats

1. SSS default: business employer 2025 schedule; MSC rounded to prescribed ₱500 salary-credit bracket, bounded ₱5,000–₱35,000. Employee 5%, employer 10%, employer-only EC ₱10/₱30. Deducted in second semi-monthly period and snapped per record. Company accountants must verify legal rates and special membership categories before payment.
2. This conversion preserves the original semi-monthly period assumptions; payroll for daily wage, hourly, contractors, weekly or biweekly employees is **not yet implemented**. UI requires `pay_basis=monthly` intentionally, to avoid miscalculating wages.
3. Company leave credits are deliberately **not** automatically generated with government's VL/SL 1.25 per month. Private eligibility rules, SIL with one year of qualifying service and exemptions, sick/vacation policy and carryover require employer setup and HR verification. Re-running seeder will not overwrite existing government leave type definitions.
4. Historical GSIS and payroll table fields remain immutable. Never run `migrate:fresh` against existing data; conversion command does not translate posted payroll into SSS. Reconcile SSS, PhilHealth and Pag-IBIG contributions for future payroll after company cutover.
5. Current OT calculation covers regular-day OT/night differential; it **does not** calculate all legal holiday/rest-day premium scenarios. Minimum wages vary by region/sector and must be implemented before production.
6. Government HR year-end and step-increment APIs are blocked for private companies. Avoid using legacy screens or exports for a private tenant.
7. Tax year-end equalization, taxable allowances, minimum wages, employment contract workflows, SIL service eligibility, loan schedules and external remittance formats still need development and accountant/legal verification.

## Operational controls and testing

- Backup database, original source and `.env` and verify restoration.
- Test migration on a clone, then check `organization_kind`, role/tenant scoping, user recovery, company departments and every migrated employee's IDs/salary/contract dates.
- Validate representative SSS boundaries (PHP 5,249.99; 5,250; 15,000; 100,000) and zero-wage/unsupported pre-2025 data. **Do not assume** pre-2025 SSS computations are supported.
- Recompute one full parallel payroll with audited time logs and known employee samples; check employee and employer shares, taxable base, BIR withholding, bank export, over/under-payment, approvals, off-cycle adjustments and settlement reconciliation.
- Run PHP test suite with all extensions enabled, `npm ci && npm run build`, `flutter analyze && flutter test`, and staging API/UI end-to-end tests.

### Official reference sources for initial rules

- Social Security System: https://www.sss.gov.ph/pay-contribution/ (business employer schedule effective January 2025)
- Department of Labor and Employment: https://bwc.dole.gov.ph/dole-bwc-urges-employers-to-release-13th-month-pay-not-later-than-december-24/
- Department of Labor and Employment, Labor Code Book 3: https://dole.gov.ph/book-3-conditions-of-employment/

Refer to the current agency notices and competent Philippine payroll/legal advisers before financial use. Do not infer 2026 rates from the 2025 rule data without checking for changes.