Tomato Hr Module Laravel Package

Technical Evaluation

Architecture fit

tomatophp/tomato-hr-module is a vertical domain module for the TomatoPHP ecosystem — a Laravel package that ships Filament resources, migrations, models, policies, and seeders for HR primitives (employees, departments, job titles/positions, attendance, leave requests, and typically payroll-adjacent records). Architecturally it is not a standalone HR library; it is a presentation-and-schema layer bound to tomato-admin / Filament conventions (service provider registration, config-driven table/route prefixes, published migrations, tomato-utils helpers, and often spatie/laravel-permission + TomatoPHP's roles module for authorization).

That makes it a good fit only if the surrounding platform is already committed to Filament and the TomatoPHP conventions (base admin panel, tomato-settings for module config, tomato-roles for ACL). In a bespoke Blade/Livewire admin, or an API-first Laravel app with no admin surface, most of the module's value is unusable and you would be inheriting migrations and models wrapped in a rendering framework you do not run.

Integration feasibility

Feasible within a day for a proof-of-concept in a clean Laravel + Filament app: composer require, register provider, php artisan vendor:publish, migrate, seed permissions, create a user, load the module routes. The realistic effort sits in the second week — reconciling the module's employee/department schema with the client's existing users, org-structure, and payroll data, and deciding whether the module's models become the system of record or a shadow of an existing HRIS.

Technical risk

• Unverified 1.0.0 semantics. The release note is a single changelog URL with no entries. We have no migration guide, no stated breaking changes, and no evidence that the pre-1.0 API was frozen deliberately rather than simply tagged. Treat "1.0.0" as a label, not a compatibility guarantee, until the commit history is reviewed.
• Ecosystem coupling. The module's stability is bounded by the least stable of its TomatoPHP siblings (tomato-admin, tomato-utils, tomato-roles, tomato-settings). A patch release in any of them can break this module, and the 1.0.0 tag pins none of them tightly by default.
• Schema ownership. HR data is high-integrity, personally identifiable, and frequently audited. Published migrations that we then extend create a fork; we own drift from upstream forever.
• Regulatory surface. Employee records, leave, and attendance touch GDPR/retention and local labour-record rules. If the package ships soft-deletes and audit columns, good; if not, we bolt them on.
• Bus factor / maintenance concentration. Single-maintainer, high-velocity multi-package ecosystem. Fine for internal tools, a procurement question for anything employee-facing.

Key questions

1. What exactly changed between the last pre-1.0 tag and v1.0.0 — any renamed tables, columns, or Filament resource paths?
2. Which tomato-* sibling packages are hard requirements, and are their versions constrained (^1.0) in composer.json?
3. Does the module own the users relationship, or does it reference an existing model via config?
4. Are migrations idempotent/publishable-only, and does it ship a down() path?
5. Is authorization enforceable per-resource via policies, or route-middleware only?
6. Is there an API/JSON surface, or is it Filament-only?
7. What is the test coverage and CI posture of the repository at the 1.0.0 tag?

Integration Approach

Stack fit

Strong fit: Laravel 10/11, PHP 8.1+, Filament 3.x, MySQL/PostgreSQL, an admin panel already built on TomatoPHP or willing to adopt Filament. Weak fit: API-first or headless backends, non-Filament admin, multi-tenant SaaS with per-tenant schema isolation (the module does not natively model tenancy — you would wrap it), and any environment where HR data must be isolated from the general admin application.

Migration path

Greenfield: install at v1.0.0, publish config and migrations, run migrations unmodified, seed the module's permission set, and treat upstream as read-only — pin the exact tag in composer.json and commit composer.lock.

Brownfield with existing HR data: do not let the module's migrations own the employee table. Two viable options:

• Adapter path (preferred): run the module against its own tables and sync from the existing HRIS via a queued importer keyed on a stable external ID. Keeps upstream upgradable.
• Fork path: publish migrations, edit for your schema, accept permanent merge conflicts. Only justified if the module is genuinely the system of record.

Either way, run the module's employee PII through your existing encryption-at-rest and retention policy before go-live, not after.

Compatibility

Pin tomatophp/tomato-hr-module:1.0.0 exactly. Verify each transitive tomato-* dependency resolves to a tag, not dev-main. Confirm Filament major version alignment (Filament 2 vs 3 resource APIs are incompatible) and check that the module's published config keys do not collide with existing config/tomato/* entries. Verify Laravel version support against the repo's composer.json require block rather than the README.

Sequencing

1. Spike (0.5 day): clean Laravel + Filament app, install, migrate, click through every resource. Confirm it renders and that permissions gate correctly.
2. Dependency audit (0.5 day): enumerate transitive TomatoPHP packages, their tags, last-commit dates, and open security advisories.
3. Changelog review: walk commits between the previous tag and v1.0.0 to reconstruct the undocumented changes.
4. Data-model decision: adapter vs fork. Get this in writing before any code is written.
5. Integrate behind a feature flag in a non-production environment; import a masked dataset.
6. Security/PII review, then staged rollout to HR staff only, then broader.

Operational Impact

Maintenance

Ongoing cost is dominated by ecosystem tracking, not by this package alone. Budget a recurring dependency-review slot each month for the tomato-* tree; a single-maintainer ecosystem ships fast and breaks occasionally. Because we pin exactly, upgrades are deliberate — expect a half-day per minor bump to re-run the resource smoke test. If we take the fork path, add the cost of manually replaying upstream migration changes.

Support

Upstream support is community/GitHub-issues with no SLA and no commercial backing apparent at this tag. Internal ownership must therefore be explicit: name a module owner, and require that at least two engineers can read the Filament resource definitions and the published migrations. Escalation for HR-data bugs during payroll or leave-cycle windows cannot depend on an external maintainer's response time.

Scaling

The module is CRUD-shaped, so read scaling is ordinary Laravel: index the foreign keys the module creates (department, manager, employee) and paginate the Filament tables. Watch three things at volume: attendance tables grow fastest and deserve partitioning or archival early; Filament resource tables with relationships generate N+1 queries unless eager loading is configured; and any dashboard/report widgets the module ships will run aggregate queries on page load. Multi-tenancy is not free — if required, plan a global scope plus tenant-aware migrations as a deliberate extension, not an afterthought.

Failure modes

• Silent schema drift after an unpinned composer update on a sibling package — mitigated by exact pins and lockfile discipline.
• Broken admin surface on a Filament major upgrade; the module's resources are the integration point and are the first casualty.
• Permission holes if the module's seeded permission set is incompletely applied — an HR module exposing salary or disciplinary records to the wrong role is a reportable incident, so verify with an explicit role matrix test, not manual clicking.
• PII leakage into non-production via seeded or imported employee data — mandate masked fixtures in the import pipeline.
• Orphaned records if the module hard-deletes employees referenced by attendance/leave — confirm soft-delete behaviour before enabling.

Ramp-up

A Laravel developer familiar with Filament can be productive on the module's resources in one to two days; the learning curve is Filament's resource/form/table API, not this package. Add one to two days for the TomatoPHP conventions (settings, roles, utils) and the publish/config workflow. Plan half a day of HR-domain walkthrough with an actual HR stakeholder — the module encodes opinions about leave accrual and attendance states that engineers will otherwise guess wrong, and correcting them post-import is expensive.