TenantAtlas/specs/085-tenant-operate-hub/research.md

Research: Tenant Operate Hub / Tenant Overview IA (Spec 085)

Date: 2026-02-09
Branch: 085-tenant-operate-hub
Spec: specs/085-tenant-operate-hub/spec.md

This research consolidates repo evidence + the final clarification decisions, so the implementation plan and tests can be deterministic.

Repository Evidence (high-signal)

• Canonical monitoring pages already exist in the Admin panel:
  • Operations index: app/Filament/Pages/Monitoring/Operations.php
  • Run detail (tenantless viewer): app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • Alerts: app/Filament/Pages/Monitoring/Alerts.php
  • Audit log: app/Filament/Pages/Monitoring/AuditLog.php
• Tenant selection + clear tenant context already exist (UI + route/controller):
  • Context bar partial: resources/views/filament/partials/context-bar.blade.php
  • Tenant select controller: app/Http/Controllers/SelectTenantController.php

Decisions (resolved)

Decision: Tenant context may use last-tenant memory for cross-panel flows

• Decision: “Tenant context is active” on Monitoring pages is resolved from the active Filament tenant when present, otherwise from the remembered last-tenant id for the current workspace.
• Rationale: Central Monitoring routes are canonical and tenantless, but users enter them from the tenant panel and expect consistent scoping.
• Alternatives considered:
  • Query param ?tenant=: rejected (would introduce an implicit switching vector).

Decision: “Show all tenants” explicitly exits tenant context

• Decision: The CTA “Show all tenants” clears tenant context (single meaning) and returns the user to workspace-wide Monitoring.
• Rationale: Prevents the confusing state where tenant context is still active but filters are reset.
• Alternatives considered:
  • Only reset table filter: rejected (context remains active and confuses scope semantics).

Decision: Stale tenant context is handled without leaks

• Decision: If tenant context is active but the user is no longer entitled to that tenant, Monitoring pages behave as workspace-wide:
  • Scope shows Workspace — all tenants
  • No tenant name is shown
  • No “Back to tenant” is rendered
  • Tenant pages remain deny-as-not-found
• Rationale: Preserves deny-as-not-found and avoids tenant existence hints.
• Alternatives considered:
  • 404 the Monitoring page: rejected (feels like being “thrown out”).
  • Auto-clear tenant context implicitly: rejected (implicit context mutation).

Decision: Run detail shows an explicit tenant return + secondary escape hatch

• Decision: When tenant context is active and entitled, run detail shows:
  • ← Back to <tenant name> (tenant dashboard)
  • secondary Show all operations → /admin/operations
• Rationale: “Back to tenant” is deterministic; the secondary link provides a canonical escape hatch.
• Alternatives considered:
  • Only show Back to tenant: rejected by clarification (secondary escape hatch approved).

Decision: Tenant panel navigation uses a “Monitoring” group with central shortcuts

• Decision: Replace the tenant-panel “Operations” item with group “Monitoring” containing shortcuts:
  • Runs → /admin/operations
  • Alerts → /admin/alerts
  • Audit Log → /admin/audit-log
• Rationale: Keep tenant sidebar labels minimal while still providing correct central Monitoring entry points, while preserving canonical URLs and avoiding tenant-scoped monitoring routes.
• Alternatives considered:
  • New tenant-scoped monitoring routes: rejected (explicitly forbidden).

Decision: “No outbound calls on render” is enforced by tests

• Decision: Monitoring GET renders must not trigger outbound network calls or start background work as a side effect.
• Rationale: Aligns with constitution (“Monitoring pages MUST be DB-only at render time”).
• Alternatives considered:
  • Rely on convention: rejected; this needs regression protection.

Open Questions

None remaining for Phase 0. The spec clarifications cover all scope-affecting ambiguities.