TenantAtlas/specs/280-workspace-tenancy-environment-routing/research.md

# Research: Filament Workspace Tenancy & Environment Routing Cutover

**Date**: 2026-05-07  
**Branch**: `280-workspace-tenancy-environment-routing`

## Decision 1: Collapse public operator routing into the existing `admin` panel

- **Decision**: `AdminPanelProvider` remains the only operator-facing Filament panel, and `Workspace` becomes the only Filament tenant for operator admin routing. `TenantPanelProvider` stops owning public operator routes.
- **Rationale**: verified repo seams show `AdminPanelProvider` already owns `/admin`, `ChooseWorkspace`, `ChooseTenant`, `WorkspaceOverview`, and the current workspace-scoped operations hub, while `TenantPanelProvider` exists only to keep the temporary `/admin/t` shell alive. Filament v5 panel configuration on Laravel 12 still expects provider registration in `apps/platform/bootstrap/providers.php`, so the narrowest truthful cutover is to remove the second operator panel rather than preserve it as a redirect shell.
- **Alternatives considered**:
  - Keep `TenantPanelProvider` as a redirect-only shell: rejected because it preserves the same split public truth and adds compatibility behavior the spec forbids.
  - Introduce nested environment Filament tenancy: rejected because `ManagedEnvironment` should remain nested route context, not a second panel tenancy.

## Decision 2: Make the workspace-scoped environment chooser the canonical public environment entry surface

- **Decision**: the canonical environment chooser route lives at `/admin/workspaces/{workspace}/environments`, reusing the current workspace-bound `ManagedTenantsLanding` surface. `ChooseTenant` remains an implementation seam to absorb or delegate selection logic, but it should not survive as a second canonical public chooser route, and `/admin/w/{workspace}/managed-tenants` is retired with no redirect or alias.
- **Rationale**: `ManagedTenantsLanding` already binds a `Workspace` route parameter and lists accessible `ManagedEnvironment` records for that workspace. `ChooseTenant` currently mixes workspace recovery, selection, and redirection into the temporary tenant panel. Keeping the workspace-scoped landing as the public chooser keeps the route language aligned with the new workspace-first contract.
- **Alternatives considered**:
  - Keep both `ChooseTenant` and `ManagedTenantsLanding` public: rejected because it preserves two chooser URLs for the same operator decision.
  - Continue auto-branching from workspace selection directly into one environment dashboard: rejected because the spec treats the workspace dashboard and environment chooser as explicit decision surfaces, not hidden branching behavior.

## Decision 3: Keep `/admin` tied to workspace selection or the workspace dashboard

- **Decision**: direct `/admin` requests resolve only to workspace selection or the canonical workspace dashboard. Environment entry becomes explicit through the workspace dashboard and environment chooser instead of using `/admin` as a hidden second environment dashboard route.
- **Rationale**: the spec requires `/admin` to remain the operator entrypoint only, not a second canonical environment route. This keeps the workspace dashboard as the primary decision surface and removes the need to infer operator scope from a remembered environment.
- **Alternatives considered**:
  - Keep `/admin` auto-redirecting into one environment when possible: rejected because it weakens the workspace-first shell and makes route truth dependent on remembered tenant context.
  - Leave `/admin` ambiguous between workspace and environment dashboards: rejected because it preserves the current split truth.

## Decision 4: Reuse the existing workspace and environment dashboards under new route ownership

- **Decision**: `WorkspaceOverview` plus `WorkspaceOverviewBuilder` remain the workspace dashboard, and `TenantDashboard` plus `TenantDashboardSummaryBuilder` remain the managed-environment dashboard. The slice changes route ownership, breadcrumbs, context-bar signals, and deep links only.
- **Rationale**: current repo truth already has the signal builders and widget families needed for this slice. The missing piece is not new dashboard content, but the temporary panel and route shell around it.
- **Alternatives considered**:
  - Build new dashboard pages for workspace-first routing: rejected because it would duplicate existing signal ownership and absorb UI work the spec explicitly defers.
  - Refactor builder ownership now: rejected because provider extraction and copy neutralization are deferred to later specs.

## Decision 5: Move operations into a workspace-first route family through shared navigation builders

- **Decision**: `/admin/workspaces/{workspace}/operations` and `/admin/workspaces/{workspace}/operations/{run}` become the canonical operations routes, and `OperationRunLinks`, `RelatedNavigationResolver`, and `Monitoring\Operations` remain the only shared seams for retargeting collection/detail URLs, environment filters, and back-navigation context. The legacy `/admin/operations` family is retired with no redirect or alias.
- **Rationale**: `Monitoring\Operations` already models `managed_environment_id`, `tenant_scope`, `problemClass`, `activeTab`, and navigation context as workspace-scoped state. The current defect is the public route family and back-link language, not the monitoring page itself.
- **Alternatives considered**:
  - Keep `/admin/operations` as the canonical route: rejected because the spec explicitly requires the workspace-first operations family.
  - Add environment-local operations pages: rejected because the operations hub is already the canonical shared monitoring surface.

## Decision 6: Update middleware, route categorization, and panel-context resolution together

- **Decision**: `EnsureWorkspaceSelected`, `EnsureFilamentTenantSelected`, `TenantPageCategory`, `ResolvesPanelTenantContext`, and `WorkspaceRedirectResolver` must move to the workspace-first environment family in the same implementation slice.
- **Rationale**: those seams currently special-case `/admin/t`, `/admin/tenants/{environment}`, workspace-canonical `/admin/operations`, and current panel ID. Partial updates would leave stale remembered environment context, wrong 404/403 handling, or mixed breadcrumb language.
- **Alternatives considered**:
  - Route redirects only: rejected because redirects would preserve the old route language and leave classifier logic stale.
  - Query-parameter-only environment context: rejected because the spec requires canonical workspace-first environment routes, not implicit query-driven context.

## Decision 7: Keep global search truthful only where destinations remain valid

- **Decision**: the touched search-eligible surfaces are `WorkspaceResource` and `TenantResource`. Each remains globally searchable only if it still has a valid view or edit destination under the workspace-first route contract; otherwise search is disabled in the same slice.
- **Rationale**: Filament v5 global search requires a resource to have a view or edit page in order to produce valid results. Current repo truth shows most other touched resources are already `isGloballySearchable = false`, so the search review surface is small and explicit.
- **Alternatives considered**:
  - Leave current global search behavior unchanged and fix later: rejected because it can leave broken results or inaccurate hints immediately after the route cutover.

## Decision 8: Prove the cutover with focused feature coverage, one browser smoke, and grep/guard checks

- **Decision**: use focused feature tests for routing and authorization, one browser smoke for the workspace-to-environment-to-operations path, and explicit grep/guard checks for `/admin/t` and `panel: 'tenant'` regressions.
- **Rationale**: Filament documentation emphasizes testing authorization and Livewire page behavior end to end, and the riskiest regression here is the live entry flow across chooser, dashboard, and operations surfaces. One narrow browser smoke is enough; broader browser or governance suites would be disproportionate.
- **Alternatives considered**:
  - Feature tests only: rejected because they would not prove the live chooser-to-dashboard flow on the surviving panel.
  - Broad browser suite: rejected because it would create a new heavy cost center for a routing cutover slice.

## Final Research Outcome

- The final operator runtime should have one public panel and one public route language rooted in workspace scope.
- The workspace-scoped environment chooser should become the public environment entry surface, with `ChooseTenant` absorbed into the same flow rather than preserved as a second public chooser URL.
- The legacy chooser route `/admin/w/{workspace}/managed-tenants` and the legacy operations family `/admin/operations` must not survive as redirects, aliases, or hidden fallback readers.
- The workspace dashboard and managed-environment dashboard should be reused as-is under new route ownership.
- Operations routing should move through the shared builders and preserve explicit environment scope via `managed_environment_id` and back-link context.
- Middleware, page categorization, and panel-context resolution must change together so deny-as-not-found and remembered-context semantics stay correct.
- Global search must remain truthful for `WorkspaceResource` and `TenantResource` or be disabled in the same slice.
- The narrowest honest proof is feature coverage, one browser smoke, and grep/guard checks.