Activity Timeline Laravel Package

Product Decisions This Supports

• Build vs. buy, scoped narrowly. The only thing being bought here is the presentation layer: a Filament v5 widget that renders an existing spatie/laravel-activitylog feed. It records nothing. That means the build-vs-buy analysis is cheap and fast — the audit backbone (Spatie plus its activity_log migration) is a decision you'd have to make either way, and this package only removes the UI work on top. Frame the comparison as "custom Blade timeline partial vs. a maintained widget," not "audit system vs. no audit system."

• Roadmap sequencing for history features. Unblocks a recurring backlog class: order/ticket/account change history, "who changed this and when," support-facing investigation views. Treat it as a fast follower to whatever admin-panel work is already shipping, not a standalone initiative that needs its own business case.

• Surface selection — the actual PM call. Three genuinely different products are in scope: (a) a record-scoped history tab on a resource View page, (b) an embedded infolist entry on custom pages, and (c) a panel-wide "audit dashboard" across all activity. (a) and (b) are low-risk and high-value; ship those first. (c) is a separate feature with a separate risk profile — it exposes cross-record and potentially cross-tenant activity and needs an access policy decision before it needs engineering time.

• UX density as a deliberate lever. The compact option added in 5.0.3 is a product decision, not a CSS tweak. It lets a timeline sit in a sidebar widget, modal, or infolist embed where vertical space is scarce, while the dedicated history tab keeps the full layout. Decide density per placement up front rather than shipping one variant everywhere and fielding complaints about sprawl or truncation.

• Data governance — product-owned, not engineering-owned. activity_log stores old/new attribute values verbatim, so fields hidden in forms may still surface in the timeline unless logOnly() / dontLogEmptyChanges() are configured. "What does the customer see about themselves, and what do our staff see about them?" is a product and privacy question. Own it explicitly; don't defer it to whoever wires up the trait.

• Retention policy with a cost attached. activity_log never prunes itself. A retention window and scheduled cleanup are required, and that window (how far back must support be able to look?) is a product/compliance choice that directly affects query performance. Decide at adoption, not after the first slow page.

• Audit-readiness positioning, honestly bounded. This is a credible, demonstrable step toward internal visibility and faster support triage. It is not an immutable audit trail — no retention guarantees, no tamper-evidence, no certification. Use it for "recent activity" expectations; do not let it answer a compliance questionnaire without legal/security review.

When to Consider This Package

Consider it when:

• You are on Laravel + Filament v5, on or near the 5.7.x line that 5.0.3 pins against. Keep the panel and the plugin on the same minor line — Filament minors have historically shifted view internals.
• You already use spatie/laravel-activitylog or are prepared to adopt it. Budget onboarding as two installs, not one, plus product time to decide what gets logged.
• Your need is a read-only, chronological, per-record or per-page feed for internal staff: support reviewing a ticket's history, ops checking who changed an order status, an account's recent activity on a custom page.
• You want a small, disposable surface — "a widget with fluent setters," lightly themed via config and published views. If that's acceptable, integration is days, not weeks, and the exit ramp is contained.

Look elsewhere — or build — when:

• Adoption signals don't support a strategic bet. 10 stars, 0 dependents, a single-maintainer cadence dominated by chores, docs, and Dependabot. Fine for a low-stakes widget; not a foundation. Don't let a roadmap commitment rest on it.
• You need guarantees. No published backward-compatibility policy, test-coverage visibility, or support commitment. If your release process requires upstream SLAs, this fails the bar.
• You need more than rendering. Real-time streaming, aggregation, cross-source correlation, analytics, or a searchable audit console are all out of scope.
• You are not on Filament. The package claims Blade support, but the value proposition and the maintenance attention are clearly Filament-shaped. API-only and non-Filament front ends get little here.
• Compliance is the actual driver. If the requirement is evidentiary — immutability, legal hold, certification — a rendering plugin over a mutable Eloquent-adjacent table is the wrong instrument, however good the UI looks.
• Activity volume is already large. Rendering is presentation-only; compact does nothing for query cost. Without an index on subject_type/subject_id, a retention policy, and sane pagination, this becomes the slowest page in your admin panel.

How to Pitch It (Stakeholders)

For executives — a cheap, reversible capability, not a platform bet. "We can put a change-history timeline into our admin panel in days rather than weeks, improving support visibility and giving us a credible audit-readiness story. It's a thin UI layer over activity logging we'd need anyway, MIT-licensed, and cheap to pilot and back out. Two caveats, stated plainly: it makes no compliance guarantees — it's a visibility tool, not an audit system — and it's a small, single-maintainer open-source project, so we adopt it as a component with an exit ramp, not as infrastructure."

For engineering — lead with the dependency reality and the version pin. "This is a Filament v5 plugin that renders spatie/laravel-activitylog; it doesn't record anything. Treat onboarding as two installs: activitylog plus its migration, then the plugin, panel registration, and filament:assets. Release 5.0.3 is a patch — one feature (a compact density option), docs/CI cleanup, and a Filament bump to 5.7.0 — with no migrations or breaking changes indicated, but verify that bump against our panel version before merging. Integration is Composer plus config/asset publishing; small surface, easy to wrap or fork if we diverge. Known operational items: activity_log doesn't prune itself, so schedule retention early; eager-load causer and subject on any global feed to avoid N+1; and treat logOnly() / dontLogEmptyChanges() as security controls, since old/new values are stored verbatim."

For product — sell the sequencing and the density decision. "Start with the highest-value, lowest-risk placement: a history tab on the View page of our most-edited resource — orders, tickets, whatever support opens fifty times a day. That exercises the record-scoped path we'll use 90% of the time. The 5.0.3 compact option means a dense timeline in sidebars and modals, full layout in the dedicated history tab; pick one per placement rather than toggling on resize. A panel-wide 'audit dashboard' is a separate feature with separate risk — it exposes cross-record and potentially cross-tenant activity and needs an access policy before it needs a sprint. And the two decisions that are ours, not engineering's: which fields we surface in history, and how long we retain it. Also set the expectation now that timelines start empty — nothing is backfilled, so history fills forward from launch."

Blunt bottom line for the decision meeting: adopt for internal, record-scoped activity visibility on a Filament v5 panel; pilot behind a policy; keep retention and field-visibility decisions on the product side; and write the fallback down now — the integration is thin enough that swapping the renderer, or falling back to a small custom Blade partial, is a contained cost if upstream maintenance stalls.