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

#+#+#+#+markdown

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)

1. 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.

2. 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).

3. 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.

4. 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.