TenantAtlas/specs/077-workspace-nav-monitoring-hub/research.md

Research — Workspace-first Navigation & Monitoring Hub (077)

Date: 2026-02-06
Branch: 077-workspace-nav-monitoring-hub
Spec: specs/077-workspace-nav-monitoring-hub/spec.md

Repo Reality Check (what exists today)

• Admin panel exists at /admin via app/Providers/Filament/AdminPanelProvider.php.
• System panel exists at /system with a separate auth guard (platform) via app/Providers/Filament/SystemPanelProvider.php.
• Workspace context selection exists:
  • Page /admin/choose-workspace via app/Filament/Pages/ChooseWorkspace.php
  • POST switch endpoint /admin/switch-workspace via routes/web.php
  • Workspace switcher UI in the user menu via resources/views/filament/partials/workspace-switcher.blade.php
• Navigation ambiguity is currently real:
  • When no tenant is selected, navigation is replaced with a single item labeled "Workspaces" linking to the choose-workspace page via app/Support/Middleware/EnsureFilamentTenantSelected.php.
  • Separately, the sidebar includes another "Workspaces" item linking to /admin/workspaces (workspace CRUD) via app/Providers/Filament/AdminPanelProvider.php.
• Operations is already canonical and tenantless:
  • Resource slug is /admin/operations via app/Filament/Resources/OperationRunResource.php.
  • Detail page is /admin/operations/{record}.

Decisions (resolved)

D1 — Manage workspaces stays on /admin/workspaces and follows workspace RBAC semantics (404 for non-members, 403 for missing capability)

• Decision: Treat /admin/workspaces as a workspace-scoped management surface in the tenant plane (/admin, Entra users):
  • Non-members (or out-of-scope workspace records) → 404 (deny-as-not-found)
  • Members missing required capabilities for protected actions/screens → 403
• Rationale: Aligns with the constitution RBAC-UX model (membership is the isolation boundary; capability denial is 403 after membership is established) while still preventing cross-workspace leakage.
• Alternatives considered:
  • Move management into /system panel: rejected because this feature targets the tenant plane IA. (If workspace CRUD becomes platform-admin only later, that should be handled as a separate migration spec.)

D2 — Tenant context influences Operations via server-side default filter state, not querystring

• Decision: Apply the tenant default filter server-side while keeping the canonical URL /admin/operations unchanged.
• Rationale: Matches Spec 077 clarification (Q2=A). Prevents link-sharing surprises and keeps canonical monitoring routes stable.
• Alternatives considered:
  • Querystring-based default filtering (e.g. ?tenant_id=): rejected as it makes filtered URLs the de-facto navigation target.

D3 — Missing workspace context redirects to /admin/choose-workspace and returns to the requested URL

• Decision: When a workspace-scoped page is visited without an active workspace selection, redirect to /admin/choose-workspace and then return.
• Rationale: Matches Spec 077 clarification (Q3=A) and aligns with existing /admin root override behavior in routes/web.php.

D4 — Invalid tenant context (tenant not in current workspace) is auto-cleared

• Decision: If tenant context is active but does not belong to the current workspace, clear tenant context and continue on workspace-level pages.
• Rationale: Matches Spec 077 clarification (Q4=A). Reduces “ghost tenant” behavior after a workspace switch.
• Alternatives considered:
  • Hard 404: rejected as too confusing during normal context switching.

Key Implementation Implications (for planning)

• Rename navigation labels to satisfy “one label, one meaning”:
  • The “Workspaces” navigation item that points to the choose-workspace page must become "Switch workspace".
  • The “Workspaces” navigation item that points to CRUD must become "Manage workspaces" and be capability-gated with workspace RBAC semantics (404 for non-members; 403 for missing capability).
• Operations filter chip/removal: current behavior filters by Tenant::current() inside OperationRunResource::getEloquentQuery(), which is not user-removable. The plan should move this behavior into a table filter with default state.
• No render-time external calls: monitoring pages must remain DB-only at render (already consistent with constitution).