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

Implementation Plan: Spec 085 — Tenant Operate Hub / Tenant Overview IA

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

Summary

Make central Monitoring pages feel context-aware when entered from the tenant panel, without introducing tenant-scoped monitoring routes and without implicit tenant switching.

Key outcomes:

• Tenant panel sidebar replaces “Operations” with a “Monitoring” group of shortcuts (Runs/Alerts/Audit Log) that open central Monitoring surfaces.
• /admin/operations becomes context-aware when tenant context is active: scope label shows tenant, table defaults to tenant filter, and header includes Back to <tenant> + Show all tenants (clears tenant context).
• /admin/operations/{run} adds deterministic “back” affordances: tenant back link when tenant context is active + entitled, plus secondary Show all operations; otherwise Back to Operations.
• Monitoring page render remains DB-only: no outbound calls and no background work triggered by view-only GET.

Technical Context

Language/Version: PHP 8.4 (Laravel 12)
Primary Dependencies: Filament v5, Livewire v4, Laravel Sail, Tailwind CSS v4
Storage: PostgreSQL (Sail)
Testing: Pest v4 (vendor/bin/sail artisan test)
Target Platform: Web (enterprise SaaS admin UI)
Project Type: Laravel monolith (Filament panels + Livewire)
Performance Goals: Monitoring page renders are DB-only, low-latency, and avoid N+1 regressions
Constraints:

• Canonical monitoring URLs must not change (/admin/operations, /admin/operations/{run})
• No new tenant-scoped monitoring routes
• No implicit tenant switching (tenant selection remains explicit POST)
• Deny-as-not-found (404) for non-members/non-entitled; 403 only after membership established
• No outbound calls on render; no render-time side effects (jobs/notifications) Scale/Scope: Small-to-medium UX change touching tenant navigation + 2 monitoring pages + Pest tests

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first / snapshots: Not applicable (read-only monitoring UX).
• Read/write separation: PASS (changes are navigation + view-only rendering; the only mutation is explicit “clear tenant context” action).
• Graph contract path: PASS (no new Graph calls).
• Deterministic capabilities: PASS (uses existing membership/entitlement checks; no new capability strings).
• Workspace isolation: PASS (non-member workspace access remains 404).
• Tenant isolation: PASS (no tenant identity leaks when not entitled; tenant pages remain 404).
• Run observability: PASS (view-only pages do not start operations; Monitoring stays DB-only).
• RBAC-UX destructive confirmation: PASS (no destructive actions added).
• Filament UI Action Surface Contract: PASS (we’re modifying Pages; we will provide explicit header actions and table/default filter behavior; no new list resources are added).

Project Structure

Documentation (this feature)

specs/085-tenant-operate-hub/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── openapi.yaml
└── tasks.md

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   ├── Resources/
│   └── ...
├── Http/
│   ├── Controllers/
│   └── Middleware/
├── Providers/
└── Support/

resources/views/
tests/Feature/
routes/web.php

Structure Decision: Laravel monolith with Filament panels. Changes will be localized to existing panel providers, page classes, shared helpers (if present), and feature tests.

Phase Plan

Phase 0 — Research (complete)

Outputs:

• specs/085-tenant-operate-hub/research.md (decisions + alternatives)

Phase 1 — Design & Contracts (complete)

Outputs:

• specs/085-tenant-operate-hub/data-model.md (no schema changes; context rules)
• specs/085-tenant-operate-hub/contracts/openapi.yaml (canonical routes + clear-tenant-context POST)
• specs/085-tenant-operate-hub/quickstart.md (manual verification)

Phase 2 — Implementation Planning (next)

Implementation will be executed as small, test-driven slices:

1. Tenant panel navigation IA

• Replace tenant-panel “Operations” entry with “Monitoring” group.
• Add 3 shortcut items (Runs/Alerts/Audit Log).
• Verify no new tenant-scoped monitoring routes are introduced.

2. Operations index context-aware header + default scope

• If tenant context active + entitled: show scope Tenant — <name>, default table filter = tenant, CTAs Back to <tenant> and Show all tenants.
• If no tenant context: show scope Workspace — all tenants.
• If tenant context active but not entitled: behave workspace-wide (no tenant name, no back-to-tenant).

3. Run detail deterministic back affordances

• If tenant context active + entitled: ← Back to <tenant> plus secondary Show all operations.
• Else: Back to Operations.

4. Pest tests (security + UX)

• OperationsIndexScopeTest (tenant vs workspace scope labels + CTAs)
• RunDetailBackToTenantTest (tenant-context vs no-context actions)
• Deny-as-not-found coverage for non-entitled tenant pages
• “No outbound calls on render” guard for /admin/operations and /admin/operations/{run}

Complexity Tracking

No constitution violations expected.