ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
d67e2c84bc
TenantAtlas/specs/107-workspace-chooser/research.md

9.1 KiB
Raw Blame History

Research: Workspace Chooser v1

Feature: 107-workspace-chooser | Date: 2026-02-22

R1: Middleware Refactor Strategy

Question: Should we create a new EnsureActiveWorkspace middleware or refactor the existing EnsureWorkspaceSelected?

  • Decision: Refactor the existing EnsureWorkspaceSelected middleware in-place.
  • Rationale: The existing middleware is already registered in both AdminPanelProvider and TenantPanelProvider middleware stacks as 'ensure-workspace-selected', and referenced by alias in bootstrap/app.php. Creating a new class would require changing all registration points and updating existing tests. The current class already handles the same responsibilities — it just doesn't implement them according to the spec.
  • Alternatives considered:
    • New EnsureActiveWorkspace class: rejected because it would require renaming the middleware alias everywhere, with no functional benefit beyond a name change. The alias can remain ensure-workspace-selected for backward compatibility.

R2: Audit Event Integration Pattern

Question: How should workspace selection audit events be emitted?

  • Decision: Call WorkspaceAuditLogger::log() directly from the middleware (for auto-selections) and from ChooseWorkspace::selectWorkspace() (for manual selections). No events/listeners needed.
  • Rationale: WorkspaceAuditLogger is a simple synchronous service — no queue, no listener. The codebase pattern (used in workspace membership, settings, alert destinations, baselines, etc.) is direct $logger->log(...) calls at the mutation point. Workspace selection audit is similarly < 1ms DB insert.
  • Alternatives considered:
    • Laravel Events + Listeners: rejected — overkill for a synchronous log write. No other systems need to react to workspace selection events.
    • Observer on User model (last_workspace_id change): rejected — would miss cases where only the session changes (auto-resume from session), and would conflate preference persistence with audit semantics.

R3: AuditActionId Enum Values

Question: What enum values and string representations to use?

  • Decision: Add two cases:
    • WorkspaceAutoSelected = 'workspace.auto_selected' — for auto-resume (single membership or last-used).
    • WorkspaceSelected = 'workspace.selected' — for manual selection from chooser.
  • Rationale: Follows the existing naming pattern (case CamelName = 'snake.dotted_value'). The method (auto/manual) and reason (single_membership/last_used/chooser) are stored in the audit log's metadata JSONB, not in separate enum values.
  • Alternatives considered:
    • Three separate enum values (one per reason): rejected — metadata provides sufficient granularity; enum values should represent the action type, not the trigger.

R4: Redirect After Selection (Tenant-Count Branching)

Question: Where does redirect logic live? Should it be deduplicated?

  • Decision: Extract the tenant-count branching logic into a shared helper method on WorkspaceContext or a dedicated WorkspaceRedirectResolver to avoid duplicating it across:

    1. EnsureWorkspaceSelected middleware (auto-resume redirects)
    2. ChooseWorkspace::selectWorkspace() (manual selection redirect)
    3. SwitchWorkspaceController::__invoke() (POST switch redirect)
    4. routes/web.php /admin route handler

    Currently, the same branching logic (0 tenants → managed-tenants, 1 → tenant dashboard, >1 → choose-tenant) is copy-pasted in all four locations.

  • Rationale: DRY — the branching is identical in all cases and is the single authority for "where to go after workspace is set." A single method eliminates the risk of divergence as new conditions are added.

  • Alternatives considered:

    • Leave duplicated: rejected — 4 copies of the same logic is a maintenance hazard.
    • Put on ChooseWorkspace page: rejected — the middleware and controller both need it but don't have access to the page class.

R5: ?choose=1 Handling Location

Question: Should the ?choose=1 forced-chooser parameter be handled in the middleware or in the page?

  • Decision: Handle in the middleware — step 2 of the algorithm. If choose=1 is present, redirect to /admin/choose-workspace?choose=1 and skip auto-resume logic.
  • Rationale: The middleware is the single entry point for all /admin/* requests. Handling it there prevents auto-resume from overriding the explicit user intent to see the chooser.
  • Alternatives considered:
    • Handle in ChooseWorkspace page: rejected — the middleware would auto-resume BEFORE the page loads, so the user would never see the chooser.

R6: User Menu Integration

Question: How to add "Switch workspace" to the Filament user menu?

  • Decision: Register via ->userMenuItems() in AdminPanelProvider::panel(). Use Filament\Navigation\MenuItem::make() with ->url('/admin/choose-workspace?choose=1') and a ->visible() callback that checks workspace membership count > 1.
  • Rationale: This is the documented Filament v5 pattern from the constitution + blueprint. The menu item is a navigation-only action (URL link), not a destructive action, so no confirmation needed.
  • Alternatives considered:
    • Context bar link only: rejected — specification explicitly requires a user menu entry (FR-008).
    • Adding to both user menu and context bar: the context bar already has "Switch workspace" — the user menu entry provides an additional discovery point per spec.

R7: Badge Rendering for Workspace Role

Question: Should workspace membership role badges use BadgeCatalog/BadgeDomain?

  • Decision: No. Workspace membership role is a tag/category (owner, admin, member), not a status-like value. Per constitution (BADGE-001), tag/category chips are not governed by BadgeCatalog. Use a simple Filament <x-filament::badge> with a color mapping (e.g., owner → primary, admin → warning, member → gray).
  • Rationale: The role is static metadata, not a state transition. No existing BadgeDomain for workspace roles. Adding one would be over-engineering for 3 static values.
  • Alternatives considered:
    • Create a WorkspaceRoleBadgeDomain: rejected — violates the "tag, not status" exemption in BADGE-001.

R8: Blade Template vs. Livewire Component for Chooser

Question: Should the chooser cards remain as a Blade template or be converted to a Livewire component?

  • Decision: Keep as Blade template rendered by the existing Livewire-backed ChooseWorkspace Filament Page. The page class already extends Filament\Pages\Page (which is Livewire). The wire:click for "Open" calls the existing selectWorkspace() method. No separate Livewire component needed.
  • Rationale: The existing pattern works. The page is already a Livewire component (all Filament Pages are). Converting to a separate Livewire component adds complexity with no benefit — the chooser has no real-time reactive needs.
  • Alternatives considered:
    • Separate WorkspaceChooserCard Livewire component: rejected — unnecessary abstraction for a simple card grid.

R9: Existing SwitchWorkspaceController Coexistence

Question: The chooser currently uses POST to SwitchWorkspaceController. Should we switch to Livewire wire:click or keep the POST?

  • Decision: Migrate the chooser page to use Livewire wire:click calling selectWorkspace($workspaceId) (which already exists). The SwitchWorkspaceController is still needed for the workspace-switcher.blade.php partial (context-bar dropdown) which uses a form POST. Both paths converge on WorkspaceContext::setCurrentWorkspace().
  • Rationale: The Livewire path already exists in ChooseWorkspace::selectWorkspace() — the blade template just needs to call it via wire:click instead of a form POST. This simplifies the chooser page and makes audit integration easier (audit logging happens in the PHP method, not in a controller).
  • Alternatives considered:
    • Keep form POST from chooser: rejected — the selectWorkspace() method is where we add audit logging. Using wire:click means a single code path.
    • Remove SwitchWorkspaceController entirely: deferred — the context-bar dropdown still uses it. Can be unified in a future PR.

R10: Flash Warning Implementation

Question: How to show "Your access to {workspace_name} was removed" when stale membership detected?

  • Decision: Use Filament database notifications or session flash + Filament\Notifications\Notification::make()->danger(). Since the middleware redirects to the chooser, and the chooser is a Filament page, Filament's notification system renders flash/database notifications automatically.
  • Rationale: The chooser is a Filament page — Filament's notification toast system is already wired. Session-based Notification::make() works for redirect→page scenarios.
  • Alternatives considered:
    • Custom Blade banner: rejected — Filament notifications already solve this and are consistent with the rest of the app.
    • Session flash only (no Filament notification): rejected — the Filament notification system provides better UX (auto-dismiss, consistent styling).