Building your own module

Open Core HR is built from Core plus modules in backend/Modules/<Name>. Your own features belong in your own module. Core updates replace Core folders but never touch Modules/, so a module you build survives every update.

Before building something, check the add-on store: a ready-made add-on may already cover it (for example Geofence Attendance, Journey Plans or Payroll), and store add-ons receive updates and support. Building your own is always fine.

Rules that keep updates safe

1. Do not edit Core files (app/, config/, database/, resources/, routes/, vendor/ …). Core updates replace them and your changes are lost. Extend Core from your module instead: its service provider, routes, migrations, permissions, menu entries and settings sections.
2. Do not edit store add-ons in Modules/. Their updates replace the folder. Copy behaviour into your own module instead.
3. Give your module a unique name with your company prefix, for example AcmeTimesheets, never the name of a store add-on. A clashing name would collide if you later install the store add-on.
4. Leave out sku in your module.json. Modules without a store code are yours: they are never licensed, updated or replaced by CZ App Studio.
5. Keep it in version control together with a record of the Core version you built it against.

Create a module

From backend/:

php artisan module:make AcmeTimesheets

Then edit Modules/AcmeTimesheets/module.json:

{
    "name": "AcmeTimesheets",
    "alias": "acmetimesheets",
    "title": "Timesheets",
    "description": "Weekly timesheets for project staff.",
    "version": "1.0.0",
    "core": "^1.0",
    "mobile": "^1.0",
    "category": "People",
    "icon": "Blocks",
    "requires": [],
    "providers": ["Modules\\AcmeTimesheets\\Providers\\AcmeTimesheetsServiceProvider"],
    "files": []
}

• core is the range of Core versions it supports. Core refuses to update to a version outside it until you widen the range, so test first, then raise it.
• requires lists other modules it needs (by name).

Switch it on from Settings → Modules. Switching on runs its migrations and registers its permissions.

What a module can contain

Look at a store add-on such as Modules/Announcements for a complete example; copy patterns, not files.

Screens and Core updates

Module screens are compiled together with Core's screens into public/build. After you add or change screens, rebuild:

npm ci && npm run build

Core updates ship assets compiled for Core and every store add-on, not your module. When an installed module's screens are not in the release, the update rebuilds the assets automatically if Node.js is available on the server, and otherwise tells you to run the command above. Until then, your module's screens do not load.

Test before you rely on it

Run the application's tests and your module's tests after building it and after every Core update:

php artisan test

Try changes on a copy of your production data, never on the live installation first. See Using AI coding agents to build modules with an agent safely.