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

# Feature Specification: Admin UI Stack Upgrade (Panel + Suite)

**Feature Branch**: `057-filament-v5-upgrade`  
**Created**: 2026-01-20  
**Status**: Draft  
**Input**: Upgrade the existing admin UI stack to the next supported major release to maintain compatibility and support, and ensure no regressions for tenant isolation and Ops-UX/Monitoring guardrails.

## Clarifications

### Session 2026-01-20

- Q: What exactly counts as a “remote call” that is forbidden during Monitoring/Operations page render? → A: Any outbound HTTP request.
- Q: Are background/automatic Livewire requests (polling, auto-refresh, hydration) allowed to make outbound HTTP calls on Monitoring/Operations pages? → A: No; Monitoring/Operations must remain DB-only even for polling/auto-refresh/hydration. Remote work is only allowed via explicit user actions that enqueue tracked operations.
- Q: Which pages count as “Monitoring/Operations” for the DB-only rule? → A: Everything rendered under the Monitoring → Operations navigation section, including all widgets/partials/tabs rendered within that section.
- Q: If a third-party package is incompatible with the upgraded stack, what remediation is allowed? → A: Upgrade/replace the package to preserve functionality. Mixed-version pinning is not allowed. If something is not realistically replaceable, treat it as an explicit scope/decision change.
- Q: Do we expect this upgrade to require any database schema/data changes? → A: Allowed only if strictly required by dependencies; must be reversible, non-destructive, backward compatible, and called out in release notes.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Admin UI keeps working after upgrade (Priority: P1)

Administrators can sign in and use the admin panel (navigation, resources, forms, tables, actions) without runtime errors after the upgrade.

**Why this priority**: This is the minimum bar for the upgrade to be safe; if the admin UI is unstable, all operational work stops.

**Independent Test**: A smoke run that signs in, loads the dashboard, opens at least one resource list + form, and executes a non-destructive action without errors.

**Acceptance Scenarios**:

1. **Given** a valid admin account, **When** they sign in and navigate through the panel, **Then** pages load without server exceptions or browser console errors.
2. **Given** an existing resource record, **When** the admin edits and saves it, **Then** the save succeeds and feedback (toast/notification) is shown.

---

### User Story 2 - Monitoring & Ops UX remain safe (Priority: P2)

Operators can use Monitoring/Operations pages and related widgets without triggering any remote calls during page rendering, and without cross-tenant leakage.

**Why this priority**: Monitoring must remain predictable and safe (DB-only at render), and tenant isolation is a core security guarantee.

**Independent Test**: Load Monitoring pages for a tenant with existing runs; verify the page renders and interactivity works while meeting the “DB-only render time” rule.

**Acceptance Scenarios**:

1. **Given** an operator viewing Monitoring for a tenant, **When** the page renders, **Then** it completes without performing any remote calls during render and without queuing background work.
2. **Given** an operator switches tenants, **When** they navigate to Monitoring again, **Then** all data shown is scoped to the active tenant.

---

### User Story 3 - Deployment remains reliable (Priority: P3)

Developers and operators can build frontend assets and deploy the upgraded application without regressions, and can roll back quickly if needed.

**Why this priority**: A framework upgrade is only useful if it can be safely deployed and reversed during incidents.

**Independent Test**: Build assets and boot the application from a clean checkout using the project’s standard local workflow.

**Acceptance Scenarios**:

1. **Given** a clean checkout, **When** dependencies are installed and assets are built, **Then** the build completes without errors.
2. **Given** a deployment with the upgraded stack, **When** operators need to revert, **Then** a documented rollback procedure can restore the previous working release.

### Edge Cases

- A third-party admin/Live UI package is incompatible with the upgraded stack.
- Users have stale browser assets after deploy and experience partial UI breakage.
- SPA navigation and global widgets fail to mount or miss events after navigation.
- Tenant switching occurs mid-session and cached UI state risks showing stale cross-tenant data.
- Monitoring pages accidentally perform remote calls during render (must be prevented/detected).

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature is an upgrade. It MUST NOT introduce new Microsoft Graph calls or new Graph write behavior.
All content rendered under the Monitoring → Operations navigation section remains “DB-only” and must not perform any outbound HTTP requests during render or during background/automatic Livewire requests (polling/auto-refresh/hydration). Tenant isolation remains mandatory.

### Functional Requirements

- **FR-001**: The application MUST upgrade the admin panel stack to the next supported major release and its required compatible reactive UI layer.
- **FR-002**: The application MUST continue to support the existing styling system without asset build failures.
- **FR-003**: All existing Filament panels MUST load successfully for authorized users and preserve core interactions (navigation, tables, forms, actions, notifications, widgets).
- **FR-004**: SPA-style navigation flows MUST continue to work, including global widget mounting and event delivery across navigation.
- **FR-005**: Everything rendered under the Monitoring → Operations navigation section (including widgets/partials/tabs) MUST remain DB-only: no outbound HTTP requests are permitted during page render or during background/automatic Livewire requests (polling/auto-refresh/hydration).
- **FR-010**: Any remote work initiated from Monitoring/Operations pages MUST be triggered only by explicit user actions (e.g., buttons) and MUST enqueue tracked operations (e.g., `OperationRun`-backed jobs) rather than performing outbound HTTP inline.
- **FR-006**: Tenant isolation MUST be preserved across requests and Live UI interactions: all reads/writes/events/caches MUST scope to the active tenant.
- **FR-007**: Compatibility risks MUST be managed by producing an explicit inventory of affected third-party packages and documenting upgrade/replacement decisions.
- **FR-011**: If a third-party package is incompatible with the upgraded stack, the system MUST preserve equivalent functionality by upgrading or replacing the package; mixed-version pinning is not allowed. Any unavoidable feature loss MUST be handled as an explicit scope/decision change.
- **FR-012**: Database migrations are allowed only if strictly required for compatibility; they MUST be reversible and non-destructive (no data loss). Migrations MUST include a safe `down()` path and avoid drops without an explicit plan, and MUST be mentioned in release notes.
- **FR-008**: The upgrade MUST not introduce new Microsoft Graph read/write behavior; if any Graph-touching behavior changes are required, they MUST be explicitly specified with safety gates and observability updates.
- **FR-009**: The upgrade MUST include a documented rollback procedure that restores the previous working state.

### Assumptions & Dependencies

- The current platform runtime versions already meet (or exceed) the minimum requirements for the next major admin UI stack release.
- Third-party UI packages used in the admin panel may need upgrades or replacements to remain compatible.
- Existing tenant isolation and “DB-only render time” guard tests (or equivalent checks) exist and remain authoritative for this upgrade.

### Key Entities *(include if feature involves data)*

- **Tenant**: The active tenant context that scopes all data access and UI state.
- **OperationRun**: The persisted record of long-running operations shown in Monitoring/Operations views.
- **AuditLog**: The tenant-scoped audit trail used to retain accountability for sensitive actions.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: An administrator can sign in and reach a usable dashboard within 60 seconds on a fresh deployment.
- **SC-002**: In regression testing, Monitoring/Operations pages render without any remote calls during render in 100% of runs.
- **SC-003**: 0 critical UI-blocking errors occur in the primary admin journeys (P1 + P2 scenarios) during manual QA.
- **SC-004**: Automated regression checks pass (100% green) for the project’s standard test run.