Skip to main content

Developer guide

This guide is for developers, integrators, and system administrators who build, extend, or operate OpenHR PH. Start here, then follow the reading order that matches your task.

  1. Architecture — how the application is put together.
  2. Local development — get a working environment.
  3. Admin panel — how the Livewire admin works and how to extend it.
  4. Payroll engine — the Go engine and statutory tables.
  5. Government and Private sectors — sector policy, catalogues, and the regulatory research matrix.
  6. Testing — Pest, Playwright, and Go tests.
  7. Multi-tenancy — tenant resolution and scoping rules.
  8. Troubleshooting — common setup and runtime failures.
  9. AWS AMI deployment — production infrastructure.

Repository map​

PathWhat lives there
app/Application code: Livewire admin, models, policies, services, jobs, console commands, and Filament integrations
app/Livewire/Admin/First-party admin panel: resources, fields, filters, actions, metrics, lenses, payroll, settings
app/Livewire/Portal/Employee self-service portal
app/Support/Tenancy/Tenant context, scopes, cache helpers, and exceptions
app/Services/Payroll/PHP payroll engine fallback and the Go engine wrapper
app/Services/Statutory/Philippines/Philippine statutory calculators (SSS, PhilHealth, Pag-IBIG, GSIS, BIR)
app/Sectors/Sector policy, catalogues, and the sector manager
bootstrap/Laravel bootstrap, middleware, and health route
config/Application configuration, including admin.php, payroll.php, and tenancy.php
database/migrations/Application migrations; the only source of truth for the schema
database/seeders/Seeders, including the plantilla seeder
database/factories/Model factories
deploy/aws/Packer AMI and Terraform stack
docs/User, developer, deployment, and security documentation
e2e/Playwright browser tests
payroll-engine/Go payroll engine, statutory rules, and tests
public/Web root, compiled assets, and public uploads
resources/css/Tailwind CSS and the ui-* design system
resources/js/Vite entry point
resources/views/Blade layouts, Livewire views, and components
routes/Web, API, admin, portal, channel, and integration routes
storage/Logs, framework cache, sessions, and uploaded files (not all tracked)
tests/Pest/PHPUnit unit and feature tests

Conventions​

  • PHP follows the project's Pint configuration and the rules in AGENTS.md.
  • The admin panel uses its own Resource/Field/Action classes, not Filament classes.
  • Tenant-owned models use BelongsToTenant; see Multi-tenancy.
  • UI work uses the ui-* classes in resources/css/app.css.
  • Add tests for behavior changes. See Testing.

Where to make a change​

TaskStart here
Add or change an admin CRUD screenapp/Livewire/Admin/Resources/
Add a field typeapp/Livewire/Admin/Fields/ and resources/views/livewire/admin/fields/
Add a filterapp/Livewire/Admin/Filters/
Add a row/toolbar actionapp/Livewire/Admin/Actions/
Add a dashboard metricapp/Livewire/Admin/Metrics/
Change the admin menuconfig/admin.php and app/Livewire/Admin/Support/Navigation.php
Change payroll rulespayroll-engine/internal/ and config/payroll.php
Change sector rules or cataloguesapp/Sectors/, config/sectors.php, and docs/developer-guide/sectors.md
Change tenancy behaviorapp/Support/Tenancy/ and docs/tenancy.md
Change UI tokensresources/css/app.css
Change deploymentdeploy/aws/ and docs/deployment/