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

Branch: 057-filament-v5-upgrade | Date: 2026-01-20 | Spec: specs/057-filament-v5-upgrade/spec.md Input: Feature specification from specs/057-filament-v5-upgrade/spec.md

Summary

Upgrade the admin UI stack from Filament v4 to Filament v5 (and Livewire v4 as a required dependency), while preserving TenantPilot’s constitution guardrails:

Monitoring → Operations pages (including widgets/partials/tabs) remain DB-only during render and during background Livewire requests (polling/auto-refresh/hydration): no outbound HTTP.
Tenant isolation remains mandatory across all UI interactions.
No new Microsoft Graph behavior is introduced.

Key compatibility decision: two Composer dependencies are Filament v4-only and will block the upgrade:

pepperfm/filament-json:^4 (requires filament/filament:^4.0)
lara-zeus/torch-filament:^2 (requires filament/filament:^4.0)

The plan replaces their in-app usage with first-party Blade-based renderers (Torchlight Engine already present) so we can move the stack forward without mixed-version pinning.

Technical Context

Language/Version: PHP 8.4.15 (project requires php:^8.2)
Framework: Laravel 12
Admin UI: Filament v4 → v5
Reactive UI: Livewire v3 → v4 (required by Filament v5)
Frontend Tooling: Vite 7, Tailwind CSS v4 (already in use), @tailwindcss/vite
Storage: PostgreSQL (operations tracked via operation_runs and JSONB columns per repo history)
Testing: Pest (Feature + Unit), PHPUnit 12 runner via php artisan test
Target Platform: Docker/Sail-first locally; Dokploy for staging/prod
Constraints:

Monitoring → Operations: DB-only render and background Livewire requests; no outbound HTTP.
All Graph calls stay behind GraphClientInterface + config/graph_contracts.php.
No new Graph endpoints/behavior introduced by this upgrade.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Inventory-first / Snapshots-second: unaffected by UI framework upgrade.
Read/write separation: unchanged; no new writes introduced.
Graph contract path: unchanged; the upgrade must not add new Graph calls.
Deterministic capabilities: unchanged.
Tenant isolation: must be preserved; audit all Filament/Livewire touchpoints that depend on tenant context.
Run observability: unchanged; ensure Monitoring pages remain DB-only at render time.
Automation / idempotency: unchanged.
Data minimization / safe logging: unchanged.

Gate status (pre-research): PASS (no justified violations required).

Project Structure

Documentation (this feature)

specs/057-filament-v5-upgrade/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit.tasks) - NOT created here

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   └── Monitoring/Operations.php
│   └── Resources/
├── Livewire/
│   └── BulkOperationProgress.php
├── Models/
│   └── OperationRun.php
└── Providers/
   └── Filament/AdminPanelProvider.php

resources/
├── views/
│   ├── filament/
│   │   ├── pages/monitoring/operations.blade.php
│   │   ├── infolists/entries/snapshot-json.blade.php
│   │   └── infolists/entries/normalized-diff.blade.php
│   └── livewire/bulk-operation-progress.blade.php
└── css/filament/admin/theme.css

Structure Decision: single Laravel web application; no new top-level folders required.

Phase 0 — Research (output: research.md)

See specs/057-filament-v5-upgrade/research.md for:

Version compatibility matrix (Filament v5 requires PHP ^8.2; Livewire v4 supports Laravel 12).
Third-party blockers and the replacement approach (drop Filament-v4-only plugins; keep Torchlight Engine for code rendering; implement a small in-app JSON renderer).
Livewire v4 migration hotspots in this repo (polling + livewire:navigated behavior, wire:model.live usage).

Phase 1 — Design (outputs: data-model.md, contracts/*, quickstart.md)

Data model: no intended schema changes; validate no new migrations are required by Filament/Livewire upgrades.
Contracts: no new HTTP/API contracts; explicitly confirm “no Graph changes”.
Quickstart: Sail-first local validation plus minimal smoke checks for Monitoring DB-only behavior.

Gate status (post-design): PASS (no new Graph calls; Monitoring remains DB-only by design).

Phase 2 — Implementation Outline (NOT executed by /speckit.plan)

Dependency upgrade

Update Composer constraints: filament/filament:^5, ensure Livewire resolves to ^4.
Remove/replace Filament v4-only plugins (pepperfm/filament-json, lara-zeus/torch-filament) and update in-app rendering.

UI migration + compatibility

Run Filament upgrade commands as required by Filament v5.
Fix breakages in custom panel/provider config (app/Providers/Filament/AdminPanelProvider.php).
Validate Livewire event and polling behavior (global Ops UX widget).

Guardrail verification

Monitoring → Operations pages: verify no outbound HTTP happens during render/poll requests.
Tenant switching: verify UI state and Livewire component data remains tenant-scoped.

Tests

Add/update targeted Pest tests for:
- Monitoring pages render without HTTP calls (use HTTP fake + assertions).
- Ops UX progress widget remains DB-only and tenant-scoped.
Run minimal suite locally (Sail-first), then broaden as needed.

5.8 KiB Raw Blame History Unescape Escape