TenantAtlas/specs/129-workspace-admin-home/research.md

# 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.