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 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)

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)

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.