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.