TenantAtlas/specs/031-tenant-portfolio-context-switch/plan.md

Plan: Tenant Portfolio & Context Switch (031)

Branch: feat/031-tenant-portfolio-context-switch
Date: 2026-01-04
Input: spec.md

Approach

1. Decide on the tenant context mechanism:
   • Preferred: Filament tenancy (tenant in URL) + built-in tenant switcher.
   • Fallback: session-based Current Tenant + visible banner (avoid global/DB state as “source of truth”).
2. Add data model pieces:
   • tenant membership/role mapping
   • tenant environment attribute
   • optional user preferences (favorites + last used)
3. Implement a single TenantContext resolver (HTTP + console) and central authorization gate/policy:
   • deny-by-default if no access
   • keep INTUNE_TENANT_ID as console override for automation
4. Update tenant-scoped resources/services to use TenantContext instead of Tenant::current() and ensure base queries are tenant-scoped.
5. Extend TenantResource into a portfolio view:
   • access-scoped query
   • environment/health columns
   • “Open” action + “Sync” action
   • bulk “Sync selected”
6. Add restore guardrails:
   • target tenant badge/header on restore pages
   • type-to-confirm includes tenant/environment (e.g. RESTORE PROD)
7. Add targeted Pest tests for authorization, context switching, and bulk sync.
8. Run Pint + targeted tests; document rollout/migration notes.

Decisions / Notes

• Avoid a global tenants.is_current UI context (unsafe for MSP); prefer per-user context.
• Avoid storing Current Tenant in the users table as the source of truth (cross-tab risk); prefer route/session context, optionally persisting “last used” separately.
• Start with user-based tenant memberships; extend to organization/group principals later if needed.
• Prefer deriving portfolio stats via relationships (withCount, withMax) initially; add denormalized summary columns only if needed for performance.