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

This quickstart is for validating the upgrade locally (Sail-first) and performing focused smoke checks.

## Prerequisites

- Docker + Docker Compose (for Sail)
- Node.js + npm

## Baseline (pre-upgrade)

Record these versions before changing dependencies so rollback is straightforward:

- Composer (from composer.json):
  - `filament/filament`: `^4.0`
  - `livewire/livewire`: transitive (will become `^4` when upgrading to Filament v5)
  - `pepperfm/filament-json`: `^4`
  - `lara-zeus/torch-filament`: `^2.0`
- Frontend (from package.json):
  - `vite`: `^7.0.7`
  - `tailwindcss`: `^4.0.0`
  - `@tailwindcss/vite`: `^4.0.0`

## Local Setup (Sail-first)

From repo root:

- Start containers: `./vendor/bin/sail up -d`
- Install PHP dependencies: `./vendor/bin/sail composer install`
- Install JS dependencies: `npm install`
- Run migrations: `./vendor/bin/sail artisan migrate`
- Build assets: `npm run build` (or `npm run dev` while iterating)

## Focused Validation Checklist

### 1) Admin UI smoke

- Sign in.
- Load the Filament dashboard.
- Open at least one resource list/table and one resource form, and save a non-destructive edit.

### 2) Monitoring → Operations guardrails (DB-only)

Goal: everything under Monitoring → Operations must stay DB-only during render and during background Livewire requests.

Manual smoke:

- Open Monitoring → Operations page.
- Leave the page open while:
  - a global widget polls (Ops UX progress widget), and
  - Livewire components hydrate.
- Verify no remote HTTP calls are triggered by rendering or background Livewire requests.

Implementation verification guidance (for the later implementation phase):

- Add a targeted Pest feature test that uses `Http::fake()` and asserts no requests were sent while rendering Monitoring pages.

### 3) Tenant isolation sanity

- Switch tenant using the app’s tenancy switcher.
- Re-open Monitoring → Operations.
- Verify all visible runs are scoped to the selected tenant.

## Tests

Run the minimum relevant tests first:

- Single file: `./vendor/bin/sail artisan test tests/Feature/...`
- Filter: `./vendor/bin/sail artisan test --filter=...`

## Formatting

Before finalizing implementation:

- `./vendor/bin/sail php ./vendor/bin/pint --dirty`

## Common Issues

## Migrations note

- The Filament v5 / Livewire v4 upgrade does not introduce new vendor-required migrations.
- If you see pending app migrations (e.g. `2026_01_18_000001_drop_bulk_operation_runs_table`), apply them as usual with `./vendor/bin/sail artisan migrate`.

- Vite manifest errors after upgrading dependencies: run `npm run build` (or `npm run dev`) and refresh.
- Browser caching after deploy: hard refresh / clear cache to pick up new Filament/Livewire assets.

## Rollback (fast path)

If the Filament v5 / Livewire v4 upgrade needs to be reverted in a hurry:

1) Revert dependency files to a known-good commit (or restore the pre-upgrade versions):
  - `composer.json` + `composer.lock`
  - `package.json` + lockfile

2) Re-install dependencies and rebuild assets:
  - `./vendor/bin/sail composer install`
  - `npm install`
  - `npm run build`

3) Clear caches (especially if a removed package/provider was involved):
  - `./vendor/bin/sail artisan optimize:clear`

4) If Filament assets/config were published in the upgraded state, re-publish for the rolled-back version (only if needed):
  - `./vendor/bin/sail artisan vendor:publish --tag=filament-assets --force`