HR add-on installation guide

The HR add-on is delivered as one self-contained Forkiva add-on package. Install this single package; no companion package is required.

Install the single add-on archive once. After extraction, its final location must be:

Modules/Hr/

The package already contains everything Forkiva needs for the HR feature. Do not copy partial module files, create another package.json, or install module-specific Node dependencies.

The same packaging rule applies to other Forkiva add-ons: each add-on is one complete package installed into its matching Modules/<Name>/ directory.

Before installation

• Confirm that the add-on version supports the installed Forkiva version.
• Back up the application and database.
• Use the complete official add-on archive.
• Preserve .env, APP_KEY, storage/, and every unrelated module.

Install the package

1. Upload or copy the single HR add-on archive to a temporary private location.
2. Extract it so the module exists directly at Modules/Hr/.
3. Confirm that Modules/Hr/module.json exists. Avoid an extra nested path such as Modules/Hr/Hr/.
4. Remove the uploaded archive from any publicly accessible directory after extraction.
5. Run the following commands from the Forkiva application root:

composer dump-autoload
php artisan module:enable Hr
yarn check:modules
yarn build
php artisan forkiva:upgrade
php artisan optimize:clear

The commands register the package, include it in the unified application build, apply the supported upgrade operations, and clear stale caches. There is no second add-on installation step.

For a normal release checkout, run composer install and yarn install --frozen-lockfile before building. Do not run add-on seeders separately against an existing production database.

Verify the add-on

1. Confirm modules_statuses.json contains "Hr": true.
2. Confirm yarn check:modules and yarn build complete successfully.
3. Inspect php artisan route:list and confirm the expected HR and employee-panel routes exist.
4. Sign in with an authorized administrator and confirm the HR menu and pages load.
5. Test permissions, employees, attendance, leave, payroll-related workflows, downloads, queues, and scheduled HR jobs used by the installation.
6. Review browser network requests and Laravel logs for errors.

Common issues

Symptom	Check
HR classes cannot be found	Confirm Modules/Hr/module.json exists directly under the expected path, then run composer dump-autoload.
The add-on is inactive	Run php artisan module:enable Hr and verify modules_statuses.json.
The unified build reports missing module files	Replace the installation with the complete official add-on archive; do not assemble the package from partial folders.
HR routes or menus are absent	Run yarn check:modules, rebuild, clear Laravel caches, and confirm the user has the required permissions.
The browser displays an older version	Deploy the matching generated assets with the application release and allow existing tabs/service workers to update.

Production release

Deploy the updated Forkiva application and its generated assets together. Never edit generated assets manually, run the development server in production, or expose an uploaded add-on archive through the public web directory.