Technical Evaluation

Architecture fit

The package is a two-part integration: athwari/laravel-zkteco-adms handles ADMS device ingestion, while filament-zkteco-adms provides the administrative/reporting surface. This is a sound split — protocol concerns stay out of the presentation layer.
v1.0.1 formalizes a dual-timestamp domain model: occurred_at (normalized, used for reporting, sorting, filtering, dashboard stats) and recorded_at (original device-local, retained for audit). This is the correct pattern for attendance data, where payroll cutoffs and day boundaries must be computed in a consistent timezone while preserving what the device actually reported.
The publishable migration stub aligns the package with standard Laravel package conventions and shifts schema ownership to the host application — good for multi-tenant apps that need per-tenant migration ordering.

Integration feasibility

Migration loading changes from automatic to publish-based. This is a small but real upgrade step: existing installations must publish and run the stub before the Filament resources will function against the new timestamp columns.
Hard version coupling is introduced: filament-zkteco-adms v1.0.1 requires athwari/laravel-zkteco-adms >= v1.0.1. Both must move together.
The per-device timezone selector with PHP runtime fallback is a config surface that materially changes stored data semantics — it needs explicit validation, not silent defaults.

Technical risk

Migration ownership drift. Once published, migrations are app-owned. Future package schema changes will not apply automatically, and teams that miss the re-publish step will diverge silently.
No backfill described. Existing attendance rows will need occurred_at populated. Without a documented backfill or migration-time recompute, historical dashboards will read null or stale values while new rows populate correctly — the worst kind of partial-correctness bug.
Silent timezone misconfiguration. Falling back to the PHP runtime timezone means a device with no configured timezone inherits the server's zone. On hosts set to UTC, attendance near midnight shifts a full day, which propagates into payroll.
Tenant migration timestamp generation at publish time can produce collisions or ordering problems when published repeatedly across tenants in the same application.
Query performance is unverified: sorting, filtering, and dashboard aggregates now target occurred_at, which needs appropriate indexing to avoid table scans on high-volume attendance tables.

Key questions

Is there a backfill command or migration for existing rows' occurred_at, and is it idempotent?
What is the source of truth for device timezone — per-device column, config file, or UI? Is a missing timezone a validation error or a silent fallback?
Does the Filament resource prevent editing recorded_at (audit integrity) while permitting occurred_at correction?
Which Filament major versions and Laravel/PHP versions are supported?
Are the published migrations tenant-scoped, and how are timestamps kept unique per tenant?
What indexes ship with the stub for occurred_at?

Integration Approach

Stack fit

Assumes Laravel 10/11 on PHP 8.1+, Filament 3.x, and MySQL/Postgres. Devices push to the ADMS HTTP endpoint; the Filament panel is the operational UI. The dual-timestamp model is compatible with any downstream payroll or HR export that expects UTC-normalized records plus an audit trail.

Migration path

Update both packages in the same Composer operation and commit the lockfile together.
Run php artisan vendor:publish --tag=filament-zkteco-adms-migrations and diff the generated stub against the previously auto-loaded migrations — treat the output as a code review artifact, not a blind command.
Verify the generated tenant migration timestamp sorts after existing tables and does not collide with other tenants' published copies.
Run migrate on staging, then execute any backfill for occurred_at before enabling the new dashboards.
Set explicit timezones for every device; audit for nulls before promoting.

Compatibility

Pin both packages to compatible ranges (filament-zkteco-adms ^1.0.1 + laravel-zkteco-adms ^1.0.1) to prevent a partial upgrade that satisfies one package's constraints but not the other's timestamp expectations.
The test bootstrap change to load .php.stub migrations from both packages hints that consuming applications with their own test suites may need equivalent handling for package-provided stubs.

Sequencing

Do not deploy the Filament UI change and the schema change as separate releases. Publish + migrate + backfill + deploy should be one coordinated window. If the app must stay up, gate the new dashboard widgets behind a feature flag until occurred_at is verified for a full day boundary in at least two device timezones (including one non-UTC).

Maintenance

Two packages to track instead of one, with a strict version pairing. Budget recurring effort for re-publishing and diffing migration stubs on each release — this is the direct cost of the ownership shift in v1.0.1.
Document a runbook step: "on upgrade, publish stubs, diff, migrate, verify timezone coverage."

Support

Expect timezone configuration to be the dominant ticket category. Add a validation rule or health check that flags any device without an explicit timezone, and log whenever the PHP runtime fallback is used — an unlogged fallback is undiagnosable in production.
Support staff will confuse occurred_at and recorded_at. Label both clearly in the Filament UI (e.g., "Normalized time" vs "Device time") and surface the device timezone alongside.

Scaling

Attendance tables grow monotonically and are queried with date-range filters and dashboard aggregates. Confirm an index on (device_id, occurred_at) or equivalent before volume ramps; consider partitioning by month once row counts reach the millions.
Multi-tenant deployments multiply the migration-publishing and timezone-configuration burden per tenant. Automate publishing in the tenant provisioning pipeline.

Failure modes

Missing migration → runtime SQL errors on every dashboard widget that touches occurred_at. Loud, easy to catch.
Un-backfilled history → dashboards show correct recent data and blank/zero historical data. Silent, hard to catch, erodes trust in the reporting.
Wrong or missing device timezone → attendance shifted by hours, causing employees to appear late, absent, or double-counted at month-end. Highest-severity failure; directly impacts payroll and compliance.
Stale published stub → host schema lags package expectations after a later release; errors surface only when new code paths execute.
Tenant timestamp collision → migration ordering failures during provisioning, blocking new tenant onboarding.

Ramp-up

Low for Laravel developers — the package follows idiomatic conventions and the Filament resources are self-documenting.
Moderate for ops and support: the publish-based migration flow, per-device timezone configuration, and the two-timestamp distinction each require explicit training. Allocate a short enablement session and a written runbook before rollout, and pilot with a single site in a non-UTC timezone to validate normalization end-to-end.