Tomato Logs Module Laravel Package

Product Decisions This Supports

• Audit trail / compliance feature scoping — a turnkey, Filament-native activity log viewer means "we can show who changed what, when" moves from a bespoke engineering effort to a configuration task. That directly affects whether audit logging lands in the current quarter or slips.
• Build vs. buy for admin tooling — the decisive question is rarely "can we build a log viewer?" (yes, in a sprint) but "do we want to own retention policies, filtering UX, subject/causer resolution, and diff rendering forever?" This package answers that with the TomatoPHP ecosystem's standard trade: fast delivery, ecosystem coupling.
• Roadmap sequencing for internal admin panels — logging is a horizontal capability that other modules (users, roles, media, settings) assume exists. Adopting it early de-risks later modules that surface "last modified by" metadata.
• Incident response & support workflows — a searchable, per-record history shortens "why did this record change?" support cycles, which is a customer-support capacity decision as much as an engineering one.
• Ecosystem commitment — pulling this in is an implicit bet on the TomatoPHP module suite (Filament version, panel conventions, upgrade cadence). Treat it as a platform decision, not a package decision.
• Security/compliance positioning — if the roadmap includes SOC 2, GDPR data-processing records, or enterprise procurement questionnaires, having a first-class activity log materially shortens those conversations.

Caveat on this specific release: v1.0.0 shipped with a changelog link and no substantive release notes, so scope above is inferred from the package's role in the TomatoPHP suite rather than from documented release content. Validate against the repo's README and tests before committing.

When to Consider This Package

Adopt when:

• The application already runs TomatoPHP and/or Filament; the marginal integration cost is near zero and the UI conventions match the rest of the panel.
• You need an operator-facing log surface — filters, per-subject timelines, causer attribution — not just a database table.
• The logging model is already spatie/laravel-activitylog (or compatible); this package is a presentation layer, so you inherit a well-understood data contract.
• The team is small and the alternative is deferring audit logging entirely.

Look elsewhere or build thin when:

• The app is not on Filament — you'd be importing a framework to get a table view. Use spatie/laravel-activitylog plus a simple resource.
• You have strict compliance requirements (tamper-evidence, WORM storage, retention/erasure automation, SIEM export). A UI module does not deliver those; you need schema and pipeline decisions this package won't make for you.
• You require an active security-response posture — pin the version, review the diff surface, and confirm the maintainer's disclosure process before handling PII-adjacent data.
• High-volume write paths: unconditional model-event logging can add meaningful overhead. Verify the logging strategy is opt-in per model.
• You're on the wrong Filament major version; module suites lag framework majors, and the resulting dependency conflict can block unrelated upgrades.

Pre-adoption checklist: confirm Filament/PHP/Laravel constraints in composer.json, check test coverage and last-commit recency, verify retention/pruning is configurable, and confirm whether logs are writable by application users (they should not be).

How to Pitch It (Stakeholders)

To executives: We can deliver a working audit trail — a searchable record of who changed what and when — as a configuration exercise rather than a build project. That removes a recurring blocker from compliance questionnaires and enterprise deals, and cuts the time support spends reconstructing "why did this change?" It is free, MIT-licensed, and already aligned with the admin stack we run, so the cost is integration time and a small ongoing maintenance obligation, not license spend.

To engineering: This is a Filament presentation layer over the standard spatie/laravel-activitylog model — it does not invent a new logging schema, so we are not locked into a proprietary data shape. It gives us filtering, causer/subject resolution, and diff rendering for free. Two things to verify before we merge: that we pin the version and control Filament compatibility in composer.json, and that logging is opt-in per model so we don't tax hot write paths. If those hold, this is a net deletion of code from our backlog.

Risk framing, stated plainly: v1.0.0 is the first stable tag and its release notes were a changelog link only. We should treat the version as a starting point, pin it, and read the code before it touches production data. That is an afternoon of diligence against a feature we would otherwise spend a sprint building.