Tomato User Activities Module Laravel Package

Technical Evaluation

Architecture fit

• Laravel package with service-provider auto-discovery; integrates as a middleware/event-listener layer at the HTTP boundary plus a Filament plugin for the admin UI. That is the right architectural slot for request/activity capture — it does not require touching domain code or controllers.
• Fits only if the application is already Laravel and, for the UI half, already on Filament (ideally a TomatoPHP admin panel). It is not a general-purpose logging service and provides no value on a non-Laravel stack.
• The single largest evaluation blocker is that the two source descriptions describe different products. The repository description reads "Advanced logger… automatically log every request… each request identified by hash," while the package description reads "user activity audit trail — records user actions with metadata." Those imply different schemas, write patterns, and retention policies: a per-request HTTP access log versus a polymorphic causer/subject activity record. A v1.0.0 with an empty changelog and 0 stars cannot be assumed to be both. Resolving this ambiguity is the gating task, not a footnote.
• Composes with spatie/laravel-activitylog rather than replacing it if it turns out to be the user-activity variant; if it is the request logger, it overlaps with existing access logs and its value proposition changes materially.

Integration feasibility

• Mechanically low-cost: composer require, publish config and migrations, migrate, and register UserActivitiesPlugin::make() in the PanelProvider. No glue code expected.
• Entirely reversible: removable via composer + a down-migration, with no domain-model entanglement, provided the team resists editing published vendor views.
• Realistic effort: half-day spike to read src/ (service provider register()/boot(), migrations, models, traits/listeners), one to two days of integration and verification.

Technical risk

• Maturity: v1.0.0, single author, 0 stars, 0 dependents, last release 2024-03-09. That is a stale artifact in an ecosystem (Filament) that ships major versions on a roughly annual cadence; the version-skew risk is high, not theoretical.
• Filament major-version coupling is the most likely breakage. A mismatch surfaces as a confusing "class not found" in the panel provider, not a clean dependency conflict.
• Data protection: IP addresses and user agents are personal data under GDPR. Retention, redaction, and whether they belong in the production database at all are decisions this package may or may not support via config.
• Silent failure: cached config from before install makes the plugin no-op without an error, which reads as a broken package.
• Write amplification: a database write per request on the request path is a measurable latency and load cost on authenticated or API-heavy traffic unless queued or toggled off.
• Unbounded growth: activity tables grow monotonically; missing indexes on user_id, created_at, or polymorphic columns degrade the admin table within months.

Key questions (all unanswered by the release note)

1. What is actually captured — request-level HTTP metadata, or model create/update/delete with causer/subject and before/after diffs? Are old values persisted?
2. Which Laravel and Filament major versions are constrained in composer.json, and do they match our panel today?
3. Does the shipped migration index the columns the Filament table filters and sorts on?
4. Is logging synchronous on the request path, queued, or config-togglable? Does a logging failure fail the request?
5. Is there PII redaction and pruning support, or must we build retention ourselves?
6. What is the test coverage, and is there a commit cadence after v1.0.0?
7. Which auth guard does it resolve the causer from in a multi-guard setup?
8. Exit cost: how deeply does it depend on Filament/TomatoPHP conventions?

Integration Approach

Stack fit

• Target: Laravel + Filament admin (ideally an existing TomatoPHP panel), single-tenant or tenant-scoped via an overridden widget class, default web guard or an explicitly configured admin guard.
• Poor fit if the stack is API-only (no admin surface to browse the records), if third-party admin modules are excluded by dependency policy, or if audit evidence must be tamper-evident.

Migration path

• Spike in a throwaway branch pinned to ^1.0 (exact pin, not a range).
• Install, publish config and migrations, and review the migration file before running anything — specifically for indexes and polymorphic columns. Add a separate additive migration for missing indexes rather than editing the vendor file.
• Run in staging against a copy of realistic data volume, then observe the Filament page's query time and the app's p95 latency with the logger enabled.
• Adoption decision at the end of the spike, not before. Removal path is composer remove plus a down-migration; confirm no published assets or panel registrations are left behind.

Compatibility

• Verify Laravel and Filament version constraints against composer.json first — this is a hard gate, not a soft check.
• Confirm guard resolution in the published config if the admin panel uses a non-default guard.
• Check timezone: DB stores UTC, Filament renders in panel timezone; apparent "hours off" is a config issue, not a bug.
• Confirm the database driver supports whatever JSON/polymorphic columns the migration uses.
• Run php artisan config:clear and php artisan filament:assets after install; both failure modes are silent.

Sequencing

1. Spike branch; read the service provider and migrations; answer the key questions above.
2. Resolve the request-logger vs. activity-trail ambiguity against our actual need — if we need per-user audit, and this is a request logger, stop here.
3. Version-compatibility gate (Laravel/Filament) — reject early on mismatch.
4. Privacy and retention decision documented before any production migration runs.
5. Staging deploy with realistic volume; measure latency delta and admin page performance.
6. Wrap access behind our own repository/interface so a later swap is a one-file change.
7. Production rollout behind a config toggle, with pruning scheduled from day one.
8. Only then represent audit logging as a delivered capability to customers or in security questionnaires.

Operational Impact

Maintenance

• External community dependency with a single maintainer and no upgrade path documented; vendor/tomatophp/.../src is the de facto documentation.
• Requires disciplined version pinning and a read of the service provider on every bump. Budget a recurring line item for this, small but non-zero.
• Any modified published Blade views become upgrade friction immediately; enforce subclassing over editing as a team rule.

Support

• No vendor SLA, no named team, no security review artifacts. Acceptable for internal tooling; not a procurement-grade dependency.
• Failure triage is self-service via GitHub issues and source reading. Plan for someone on the team to own it by name.

Scaling

• Growth is monotonic and proportional to request volume, not user count — the request-logger variant scales with traffic and can outgrow expectations quickly.
• Mitigations in order of preference: queue the write off the request path (ShouldQueue), prune daily via model:prune or an equivalent scheduled command (add Prunable semantics via a subclass if absent), index the filtered columns, and only then consider partitioning.
• Admin UI performance degrades before storage does — the Filament table is the first thing to feel it.

Failure modes

• Fail-open requirement: a synchronous logger that throws on a DB error can 500 production requests. Validate that writes are wrapped or queued before enabling on the primary path.
• Silent no-op from stale config cache.
• Empty Filament page from unpublished assets, with no error.
• Class-not-found in the panel provider from a Filament major-version mismatch.
• Slow activity page from missing indexes on filtered columns.
• Compliance exposure from unbounded PII retention.
• Timezone drift in the UI producing false "last activity" reports to support.

Ramp-up

• Half-day spike for one engineer already fluent in Laravel/Filament; add a day if the team is new to TomatoPHP conventions.
• The real ramp-up cost is not installation but the investigation: schema, capture semantics, PII posture, and query behavior on realistic volume.
• Output of the spike should be a short written record of what is captured, what is retained, and how to remove it — that document is the artifact that lets the package be pitched, approved, or rejected on evidence rather than on the description.