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)

```text
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)

```text
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.