TenantAtlas/specs/057-filament-v5-upgrade/research.md

Research: Admin UI Stack Upgrade (Filament v5 + Livewire v4)

This document resolves planning unknowns for 057-filament-v5-upgrade.

Version Compatibility

Decision: Upgrade to Filament v5 and Livewire v4

• Decision: Upgrade filament/filament to ^5 and let Composer resolve livewire/livewire:^4 as required.
• Rationale:
  • Filament v5 is the next major and current supported release.
  • Livewire v4 supports Laravel 12 and PHP >= 8.1 (project is PHP 8.4.15).
  • Keeps the admin UI stack aligned with upstream support/security.
• Alternatives considered:
  • Stay on Filament v4: rejected (explicit goal is v5 upgrade).
  • Attempt mixed-version pinning (Filament v4 plugins + Filament v5 core): rejected by spec (no mixed-version pinning).

Evidence (Packagist)

• filament/filament v5.0.0 requires php:^8.2.
• livewire/livewire v4.x requires laravel/framework:^10.15|^11|^12 (Laravel 12 compatible).

Third-Party Package Compatibility

Decision: Remove Filament v4-only plugins and replace functionality in-app

Two Composer requirements are currently hard-pinned to Filament v4:

• pepperfm/filament-json:^4 -> requires filament/filament:^4.0
• lara-zeus/torch-filament:^2 -> requires filament/filament:^4.0

Because Filament v5 cannot satisfy these constraints, we must remove/replace them.

pepperfm/filament-json

• Observed in-app usage:
  • resources/views/filament/infolists/entries/snapshot-json.blade.php includes filament-json::json and sets helper closures expected by the package.
• Decision:
  • Replace the JSON viewer infolist entry with a first-party Blade renderer.
• Rationale:
  • The app already normalizes the JSON payload and provides a "Copy JSON" action.
  • A first-party renderer avoids blocking Filament v5.
  • We can reuse Torchlight Engine for syntax-highlighted JSON rendering if desired.
• Alternatives considered:
  • Wait for upstream Filament v5 support: rejected (would block the upgrade).
  • Find another third-party Filament v5 JSON plugin: possible fallback, but first-party renderer is lowest-risk/no dependency.

lara-zeus/torch-filament

• Observed in-app usage:
  • No direct usage found in app/** or resources/**.
  • Torchlight rendering is implemented directly using torchlight/engine in Blade views (e.g. normalized-diff entry).
• Decision:
  • Remove the package and keep torchlight/engine usage directly.
• Rationale:
  • Removes a Filament v4-only dependency.
  • Keeps the "code highlighting" feature via the engine the app already uses.

Livewire v4 Migration Risk Areas

Decision: Treat Livewire navigation/polling widget behavior as a primary regression surface

Observed hotspots:

• resources/views/livewire/bulk-operation-progress.blade.php
  • Uses wire:poll.5s="refreshRuns".
  • Uses a JS poller that listens for livewire:navigated and calls $wire.refreshRuns().
• resources/views/livewire/backup-set-policy-picker-table.blade.php
  • Uses wire:model.live.

Rationale:

• Livewire major upgrades commonly change lifecycle events and JS hook APIs.
• Ops UX widget is global and runs across navigation; breakage would be highly visible.

Alternatives considered:

• "Upgrade and hope": rejected; we should plan explicit regression checks.

Monitoring DB-only Guardrail Implications

Decision: Monitoring -> Operations must remain DB-only across all Livewire requests

• Definition: "remote call" means any outbound HTTP request.
• Applies to:
  • Initial render
  • Background Livewire requests (polling/auto-refresh/hydration)
• Implementation implication:
  • Any Livewire component used under Monitoring -> Operations must not call Graph/HTTP in lifecycle hooks.
  • Remote work must remain "enqueue-only" behind explicit user actions and OperationRun tracking.

Alternatives considered:

• Allowing background remote calls for freshness: rejected by spec/constitution.

Proposed Implementation Sequencing

1. Upgrade core dependencies (Filament v5 -> Livewire v4).
2. Remove/replace Filament v4-only plugins:
   • Replace snapshot JSON view
   • Remove torch-filament (retain torchlight/engine)
3. Run Filament upgrade command(s) and fix panel/provider issues.
4. Fix Livewire v4 regressions in polling + navigation event handling.
5. Add/adjust targeted tests and verify Monitoring DB-only behavior.

Implementation Outcome (Final)

Dependency decisions (as implemented)

• Filament upgraded to v5; Livewire upgraded to v4 (resolved transitively).
• Removed Filament v4-only dependencies:
  • pepperfm/filament-json
  • lara-zeus/torch-filament
• Kept code highlighting by explicitly requiring torchlight/engine (and its syntax highlighter dependency phiki/phiki).

Guardrails validated

• Monitoring -> Operations remains DB-only during initial render and during background Livewire requests (no outbound HTTP).
• Monitoring -> Operations remains tenant-scoped; cross-tenant access is forbidden.
• Monitoring render does not enqueue background work; enqueue remains behind explicit user actions.

Validation notes

• Full suite gate php artisan test run after upgrade.