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

# Implementation Plan: Workspace Home & Admin Landing

**Branch**: `129-workspace-admin-home` | **Date**: 2026-03-09 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/129-workspace-admin-home/spec.md`

## Summary

Introduce a real workspace-level home at `/admin` inside the existing admin panel by replacing the current redirect-only landing behavior with a dedicated Filament overview page. Keep workspace selection as the only precondition, preserve explicit tenant drill-down through `/admin/choose-tenant` and `/admin/t/{tenant}`, reuse existing workspace-safe monitoring and management destinations for quick actions, and implement bounded capability-safe overview widgets so the admin panel becomes the canonical workspace entry point without adding a new business panel.

## Technical Context

**Language/Version**: PHP 8.4.15 / Laravel 12  
**Primary Dependencies**: Filament v5, Livewire v4.0+, Tailwind CSS v4  
**Storage**: PostgreSQL via Laravel Sail plus session-backed workspace and tenant context  
**Testing**: Pest v4 feature tests on PHPUnit 12  
**Target Platform**: Laravel Sail web application with admin panel at `/admin` and tenant panel at `/admin/t/{tenant}`
**Project Type**: Laravel monolith / Filament web application  
**Performance Goals**: `/admin` remains DB-only at render time, overview queries are bounded and eager-loaded, and no uncontrolled polling is introduced  
**Constraints**: Keep the existing admin panel as the workspace panel; preserve workspace chooser gating; keep tenant selection explicit; avoid schema changes; avoid broad middleware refactors; enforce 404 for non-members and 403 for in-scope capability denial  
**Scale/Scope**: One new workspace overview page, a small set of workspace-safe widgets or overview sections, landing and navigation semantic changes, and focused workspace-routing and authorization regression tests

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS — no inventory or snapshot semantics change; the feature is a workspace-context view and routing correction.
- Read/write separation: PASS — no new write flow is introduced; the workspace home is read-only and links to existing destinations.
- Graph contract path: PASS — no Microsoft Graph calls are added.
- Deterministic capabilities: PASS — overview surfaces can be derived from existing workspace membership and canonical capability checks; no raw capability strings are needed.
- RBAC-UX planes and isolation: PASS — the feature stays in the `/admin` workspace plane, keeps `/system` separate, and must maintain 404 deny-as-not-found for non-members and 403 for in-scope capability denial on protected targets.
- Workspace isolation: PASS — `/admin` remains workspace-gated through `EnsureWorkspaceSelected`, and overview access remains workspace-member only.
- RBAC-UX destructive confirmation: PASS / N/A — the overview itself introduces no destructive action.
- RBAC-UX global search: PASS — no new searchable resource is added; global-search semantics remain unchanged.
- Tenant isolation: PASS — the overview stays tenantless by URL and must only surface tenant-owned aggregates through capability-safe, workspace-bounded query paths.
- Run observability: PASS / N/A — the workspace home creates no `OperationRun`; it only reads existing operational data.
- Ops-UX 3-surface feedback: PASS / N/A — no new operation lifecycle is introduced.
- Ops-UX lifecycle and summary counts: PASS / N/A — no `OperationRun` state transition or summary-count producer is added.
- Ops-UX guards and system runs: PASS / N/A — existing operations behavior is unaffected.
- Automation: PASS / N/A — no queued or scheduled workflow changes are required.
- Data minimization: PASS — overview data remains DB-derived, bounded, and free of secrets or raw payload logging.
- Badge semantics (BADGE-001): PASS — any reused alert, finding, or operations badges must come from the existing badge catalog and renderer.
- Filament UI Action Surface Contract: PASS — the new workspace overview is a view-style page with inspection and navigation affordances only; it introduces no bulk or destructive mutation surface.
- Filament UI UX-001: PASS — the page will be built as a sectioned workspace overview using cards or widgets with intentional empty states, not as a bare redirect or naked control surface.
- Filament v5 / Livewire v4 compliance: PASS — the feature stays inside the existing Filament v5 and Livewire v4 admin panel.
- Provider registration (`bootstrap/providers.php`): PASS — no new panel provider is introduced; the existing admin panel provider remains registered in `bootstrap/providers.php`.
- Global search resource rule: PASS — no new Resource is added, so the Edit/View global-search rule does not change.
- Asset strategy: PASS — no new heavy or shared asset bundle is required; current deployment behavior, including `php artisan filament:assets`, remains unchanged.
## Project Structure

### Documentation (this feature)

```text
specs/129-workspace-admin-home/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── workspace-home-routing.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)
```text
app/
├── Filament/
│   ├── Pages/
│   │   ├── ChooseWorkspace.php                # reference-only gating flow
│   │   ├── ChooseTenant.php                   # reference-only explicit tenant drill-down
│   │   └── WorkspaceOverview.php              # NEW canonical workspace home
│   ├── Pages/
│   │   └── Monitoring/
│   │       ├── Operations.php                 # reference-only canonical destination
│   │       └── Alerts.php                     # reference-only canonical destination
│   └── Widgets/
│       ├── Dashboard/                         # reference patterns for dashboard cards/lists
│       └── Workspace/                         # NEW workspace-safe overview widgets if split from page
├── Providers/
│   └── Filament/
│       └── AdminPanelProvider.php             # MODIFY — home/nav/logo semantics
├── Support/
│   ├── Middleware/
│   │   └── EnsureFilamentTenantSelected.php   # MODIFY if workspace-safe nav handling needs expansion
│   └── Workspaces/
│       ├── WorkspaceContext.php               # reference-only current workspace state
│       └── WorkspaceRedirectResolver.php      # MODIFY or narrow to explicit post-selection flows only
routes/
└── web.php                                    # MODIFY — `/admin` route semantics
resources/
└── views/
  └── filament/
    ├── admin/                             # reference-only brand logo view
    └── pages/                             # NEW workspace overview Blade view if page uses custom layout
tests/
└── Feature/
  ├── Filament/
  │   ├── AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php  # MODIFY or replace legacy expectations
  │   ├── LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php   # MODIFY for new `/admin` home behavior
  │   └── WorkspaceOverview*Test.php                                 # NEW focused landing/visibility tests
  ├── Monitoring/                                                     # reference-only operations/alerts access tests
  └── Guards/                                                         # reference-only workspace/scope guard tests
```

**Structure Decision**: Keep the feature inside the existing Laravel/Filament monolith. The implementation is a focused workspace-plane home page and routing change backed by small workspace-safe overview widgets or sections, existing monitoring/workspace destinations, and targeted Pest feature tests.

## Complexity Tracking

> No Constitution Check violations. No justifications needed.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| — | — | — |

## Phase 0 — Research (DONE)

Output:
- `specs/129-workspace-admin-home/research.md`

Key findings captured:
- `/admin` is currently a manual route closure that delegates to `WorkspaceRedirectResolver`, so the admin panel has no durable home page today.
- `EnsureWorkspaceSelected` should remain the workspace-selection gate, but direct `/admin` entry without workspace context must become chooser-first while tenant branching stops being the default meaning of `/admin`.
- Existing operations and alerts pages are already workspace-safe by route shape and middleware exceptions, which makes them suitable canonical quick-action targets.
- The admin panel already uses the brand logo view and primary navigation wiring needed to make the workspace home the canonical top-level destination.

## Phase 1 — Design & Contracts (DONE)

Outputs:
- `specs/129-workspace-admin-home/data-model.md`
- `specs/129-workspace-admin-home/contracts/workspace-home-routing.openapi.yaml`
- `specs/129-workspace-admin-home/quickstart.md`

Design highlights:
- Add a dedicated `WorkspaceOverview` Filament page at `/admin` instead of treating `/admin` as a redirect shim.
- Preserve workspace selection gating through `EnsureWorkspaceSelected`, but constrain direct `/admin` requests without workspace context to chooser-first behavior and keep `WorkspaceRedirectResolver` for explicit post-selection or legacy flows, not canonical admin-home access.
- Implement overview content as capability-safe, bounded workspace metrics and lists that link only to existing canonical destinations.
- Keep “Switch workspace” and “Manage workspaces” distinct in both navigation semantics and authorization behavior.

## Phase 1 — Agent Context Update (DONE)

Run:
- `.specify/scripts/bash/update-agent-context.sh copilot`

## Phase 2 — Implementation Outline (tasks created in `/speckit.tasks`)

### Step 1 — Introduce the canonical workspace overview page

Goal: implement FR-129-01 through FR-129-07 and FR-129-18 through FR-129-20.

Changes:
- Create a new admin-panel page class for the workspace overview and register it so `/admin` becomes a real page, not a redirect-only closure.
- Render a calm workspace-level layout with heading, workspace context, structured cards or sections, and explicit empty states.
- Ensure the page is clearly workspace-scoped and makes no tenant context claim when no tenant is active.

Tests:
- Add focused feature coverage proving `/admin` renders the workspace overview when a workspace is selected.
- Add page-access tests proving non-members receive 404 semantics and valid workspace members can access the page without a selected tenant, even when they lack most workspace capabilities.

### Step 2 — Rewire admin landing and preserve chooser gating

Goal: implement FR-129-02 through FR-129-05, FR-129-15, and FR-129-16.

Changes:
- Update `/admin` route and panel-home semantics so the workspace overview is the canonical admin landing target.
- Preserve `EnsureWorkspaceSelected` as the workspace-selection precondition for admin entry while updating direct `/admin` without workspace context to use chooser-first semantics.
- Update `EnsureWorkspaceSelected` and narrow `WorkspaceRedirectResolver` usage so chooser-driven and explicit post-selection flows can still branch deliberately without defining normal `/admin` behavior or bypassing chooser-first semantics on direct `/admin` access.
- Ensure admin-panel brand-logo clicks and future workspace-return links resolve back to `/admin`.

Tests:
- Replace or update legacy tests that currently expect `/admin` to redirect to choose-tenant, tenant dashboard, or managed-tenants index.
- Add coverage for direct `/admin` without an established workspace context continuing to choose-workspace, including single-membership and last-used-workspace auto-resume edge cases.
- Add coverage for login or post-auth admin entry landing on workspace home once workspace context exists.

### Step 3 — Register primary navigation and preserve workspace-safe panel chrome

Goal: implement FR-129-06, FR-129-13, and FR-129-14.

Changes:
- Add a stable `Overview` navigation item as the first or first relevant item in admin navigation.
- Keep “Switch workspace” as a context action and “Manage workspaces” as an authorized admin destination.
- Adjust workspace-safe navigation building where needed so the overview remains visible and coherent when no tenant is selected.

Tests:
- Add response-level or page-level assertions proving `Overview` is visible in admin navigation.
- Add coverage proving “Manage workspaces” appears only for authorized users while “Switch workspace” remains a separate context action.

### Step 4 — Implement workspace-safe summary, attention, and recent-operations surfaces

Goal: implement FR-129-08 through FR-129-12, FR-129-17, FR-129-21, FR-129-22, FR-129-23, FR-129-24, and FR-129-25.

Changes:
- Create a minimal workspace KPI surface for accessible tenants, active operations, alerts, and one needs-attention metric only when each can be computed safely and cheaply.
- Add a bounded recent-operations surface reusing canonical operations destinations.
- Add a bounded needs-attention surface based on existing alert, finding, or operation failure signals.
- Add capability-aware quick actions to choose tenant, open operations, open alerts, switch workspace, and manage workspaces when authorized.
- Keep list lengths capped and explicitly disable polling by default or set a documented conservative interval only for a lightweight surface that justifies it.

Tests:
- Add feature or widget tests proving low-permission users do not see unauthorized counts or shortcuts while retaining page access as workspace members.
- Add empty-state coverage for no tenants, no recent operations, and no urgent items.
- Add assertions that overview lists are bounded, that no tenant is required for page render, and that overview widgets do not introduce uncontrolled polling by default.

### Step 5 — Verify route semantics and contain regressions

Goal: implement the acceptance criteria around stable canonical meaning and regression safety.

Changes:
- Audit every call site currently relying on `WorkspaceRedirectResolver` and classify it as “keep explicit branching” versus “use workspace home instead.”
- Ensure tenant selection still occurs only where tenant context is actually required.
- Confirm existing operations and alerts routes remain canonical destinations from the workspace home.

Tests:
- Add regression coverage proving normal `/admin` access no longer silently redirects into tenant context.
- Preserve or extend chooser and tenant-selection tests so explicit drill-down still works after the home change.

### Step 6 — Polish layout and finalize verification

Goal: meet the UX-001 layout expectations and page-quality requirements in the spec.

Changes:
- Review section hierarchy, spacing, labels, empty-state copy, quick-action grouping, and badge usage against UX-001.
- Ensure overview content remains enterprise-style, calm, and clearly workspace-level.

Tests:
- Run focused Pest coverage for landing, authorization, low-data, and nav semantics.
- Run Pint on dirty files through Sail during implementation.

## Constitution Check (Post-Design)

Re-check result: PASS.

- Livewire v4.0+ compliance: preserved because the design remains inside the existing Filament v5 / Livewire v4 admin panel.
- Provider registration location: unchanged; the existing `App\Providers\Filament\AdminPanelProvider` remains registered in `bootstrap/providers.php`.
- Globally searchable resources: unchanged; no new Resource is introduced.
- Destructive actions: unchanged; the workspace overview adds navigation and inspection affordances only.
- Asset strategy: unchanged; no new heavy assets are introduced, and current deploy-time `php artisan filament:assets` behavior remains sufficient.
- Testing plan: add or update focused Pest feature coverage for `/admin` landing semantics, workspace selection gate preservation, admin navigation visibility, capability-safe overview rendering, low-permission/empty-state behavior, and regression protection against silent tenant redirects.