# Research: Workspace Home & Admin Landing **Feature**: 129-workspace-admin-home | **Date**: 2026-03-09 ## R1: Canonical meaning of `/admin` **Decision**: Make `/admin` render a dedicated workspace overview page whenever a workspace is already selected, and require chooser-first semantics for direct `/admin` access when no workspace is established. **Rationale**: The current implementation treats `/admin` as a manual redirect shim in `routes/web.php`, immediately delegating to `WorkspaceRedirectResolver`. That behavior conflicts directly with the feature requirement that `/admin` be a stable, tenantless workspace home. The existing `EnsureWorkspaceSelected` middleware currently auto-resumes a single or last-used workspace, so direct `/admin` entry needs a targeted adjustment: keep workspace gating, but stop auto-resume from bypassing chooser-first semantics on the canonical home route. **Alternatives considered**: - Keep `/admin` as a redirect closure and add a separate `/admin/overview` page: rejected because it would preserve the current architectural confusion and fail the requirement that `/admin` itself be the canonical workspace home. - Continue branching on tenant count through `WorkspaceRedirectResolver`: rejected because it keeps tenant context as the default destination and prevents `/admin` from being a durable return target. ## R2: Where the workspace home should live **Decision**: Add the workspace home as a new page inside the existing admin Filament panel rather than introducing a new panel or standalone Blade route. **Rationale**: The existing admin panel provider already owns the `/admin` path, navigation, brand logo, workspace-aware panel chrome, and authenticated route registration. A Filament page keeps the feature aligned with Filament v5 and Livewire v4 conventions, preserves brand-logo semantics, and allows the overview to participate in panel navigation and authorization consistently. **Alternatives considered**: - Create a third “workspace panel”: rejected because the spec explicitly forbids a new business panel and the current admin panel already represents workspace-level context. - Build a standalone Laravel route and Blade view outside Filament: rejected because it would bypass existing panel navigation, page authorization patterns, and brand/home semantics. ## R3: How to keep overview data capability-safe **Decision**: Treat workspace membership as the page-entry rule for the workspace overview, then derive every metric, list, and quick action from capability checks and suppress any surface whose safe aggregate or canonical destination cannot be authorized. **Rationale**: The constitution requires deny-as-not-found for non-members and forbids aggregate leakage across unauthorized tenant scope. The workspace home also has an explicit low-permission requirement, so a valid workspace member must still be able to open the page even if most surfaces collapse to empty or hidden states. Capabilities therefore belong on sub-surfaces and destinations, not on page entry for valid members. **Alternatives considered**: - Show broad workspace totals first and rely on destination pages to enforce authorization later: rejected because summary counts themselves can leak unauthorized scope. - Reuse tenant-bound dashboard widgets unchanged: rejected because tenant-bound widgets may assume `Filament::getTenant()` or imply tenant context when none is active. ## R4: Workspace-safe destinations and quick-action strategy **Decision**: Reuse existing canonical destinations for operations, alerts, tenant selection, workspace switching, and workspace management instead of introducing any new workflow in the home page. **Rationale**: The codebase already contains workspace-safe routes and pages for operations and alerts under `/admin`, explicit chooser pages for workspace and tenant selection, and a dedicated workspace management resource. Reusing those destinations keeps the home page lightweight, preserves semantic separation between “Switch workspace” and “Manage workspaces,” and avoids scope creep. **Alternatives considered**: - Add inline workflow actions directly on the home page: rejected because the spec excludes new workflows and the action surface should remain primarily navigational. - Link all quick actions through tenant-aware destinations even when no tenant is selected: rejected because it would reintroduce implicit tenant forcing. ## R5: Handling existing redirect helpers without breaking flows **Decision**: Narrow `WorkspaceRedirectResolver` so it remains the chooser-driven and explicit post-selection branching helper, but stop using it as the canonical meaning of normal admin-home access and stop direct `/admin` requests without workspace context from bypassing the chooser through middleware auto-resume. **Rationale**: The resolver is still needed for flows like selecting a workspace from the chooser or other explicit “continue into work” branches. Removing it entirely would create unnecessary regression risk. The real change is semantic: `/admin` should no longer call the resolver by default after workspace selection has already been established, and direct admin-home entry without workspace context should route through chooser-first semantics instead of auto-resuming silently. **Alternatives considered**: - Delete the resolver and rewrite all workspace post-selection behavior around the new home: rejected because it broadens scope and risks breaking explicit chooser flows that still benefit from tenant-count branching. - Leave every existing call site untouched: rejected because the `/admin` landing route itself must stop forcing tenant branching. ## R6: Polling and performance stance for the first workspace home **Decision**: Default to no polling on the workspace overview and use only bounded DB-backed queries with explicit result caps for recent or urgent lists. **Rationale**: The spec explicitly forbids uncontrolled heavy polling and broad workspace-wide aggregation. Existing monitoring surfaces already provide deeper operational visibility where live state matters more. The workspace home should focus on fast orientation, not live dashboard behavior. **Alternatives considered**: - Reuse existing dashboard widgets with their current polling behavior: rejected because polling assumptions may be tenant-bound or too chatty for a workspace home. - Add high-frequency refresh to keep the overview “live”: rejected because it creates avoidable load and is unnecessary for the feature’s orientation goal. ## R7: Testing strategy for the new canonical home **Decision**: Use focused Pest feature tests at the HTTP and page level to cover `/admin` landing semantics, chooser preservation, workspace-safe rendering, navigation visibility, and low-permission behavior. **Rationale**: The existing codebase already has feature tests around `/admin`, workspace selection, and chooser behavior. The home change is primarily a route, page, and authorization semantic shift, so focused feature coverage is the lowest-cost and most stable regression guard. **Alternatives considered**: - Rely only on existing redirect tests and manually inspect the UI: rejected because the legacy redirect tests currently encode the wrong behavior for this spec. - Jump directly to browser tests: rejected because the key risks are routing and authorization semantics, which are already well covered by feature-test infrastructure.