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.