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.