ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
beebbaefbe
TenantAtlas/specs/266-tenant-dashboard-productization-v1/plan.md
Ahmed Darrazi beebbaefbe
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 5m58s
Details
chore: commit all local changes
2026-05-03 16:00:44 +02:00

32 KiB
Raw Blame History

Implementation Plan: Tenant Dashboard Productization v1

Branch: 266-tenant-dashboard-productization-v1 | Date: 2026-05-02 | Spec: spec.md Input: Feature specification from spec.md

Summary

Productize the existing tenant landing route in ../../apps/platform/app/Filament/Pages/TenantDashboard.php into a calmer decision-first governance overview by collapsing the current seven-widget vertical stack into one bounded dashboard summary composition plus conditional arrival continuity. The implementation should reuse current findings, risk-exception, baseline/governance aggregate, recovery, required-permissions, review, evidence, review-pack, and operations truth rather than adding a new persisted dashboard model, a second panel, or a parallel status framework.

Filament remains on Livewire v4 under v5, tenant-panel provider registration remains where it is today in ../../apps/platform/bootstrap/providers.php, no new globally searchable resource is introduced, no destructive dashboard action is planned, and no new asset registration strategy is expected. If an existing mutation-capable action such as review-pack generation is reused from the dashboard, it must continue to flow through the current safety, audit, and OperationRun seams unchanged.

Technical Context

Language/Version: PHP 8.4, Laravel 12
Primary Dependencies: Filament v5, Livewire v4, Tailwind v4, Pest v4, existing dashboard widgets, TenantGovernanceAggregateResolver, RestoreSafetyResolver, BackupHealthDashboardSignal, OperationRunLinks, RequiredPermissionsLinks, TenantRequiredPermissionsViewModelBuilder, tenant review/evidence/review-pack resources, shared badge rendering, and capability helpers
Storage: PostgreSQL via existing tenant-owned findings, exceptions, operation runs, evidence snapshots, review packs, tenant reviews, backup or restore evidence records, memberships, and audit logs; no new persistence planned
Testing: Pest v4 feature coverage plus one bounded browser smoke slice for the tenant dashboard
Validation Lanes: confidence, browser
Target Platform: Laravel monolith in apps/platform, tenant/admin plane (/admin/t/{tenant}) plus canonical admin follow-up surfaces under /admin
Project Type: Web application (Laravel monolith with Filament pages, widgets, resources, Blade views, and shared support builders)
Performance Goals: keep dashboard rendering DB-only with no outbound HTTP, avoid N+1 queries when composing status cards, preserve tenant-prefilter continuity into canonical operations and governance inbox routes, and keep any active polling bounded to existing operation-truth behavior only
Constraints: max 2 visible header actions, max 4 KPI cards, max 3 recommended actions, no fake routes, no fake data, no new panel/provider work, no raw diagnostics in the default-visible layer, no new persisted dashboard aggregate, and no Microsoft-provider semantics leaking deeper into platform-core vocabulary
Scale/Scope: 1 tenant dashboard page, 1 bounded dashboard summary query/view-model layer, 1 conditional arrival-context strip, 6 current dashboard widgets or their absorbed logic, 6 downstream route families (governance inbox, findings, risk exceptions, operations, required permissions, review/evidence/pack), targeted feature tests, and 1 explicit browser smoke

Likely Affected Repo Surfaces

UI / Filament & Livewire Fit

  • Keep ../../apps/platform/app/Filament/Pages/TenantDashboard.php as the canonical tenant route and page shell. This slice productizes the current surface instead of adding a second tenant landing page or a new panel.
  • Replace the current vertical widget stack with one composite dashboard overview surface backed by a bounded summary query/view-model layer. The current widgets remain source seams for truth and links, but they no longer need to dominate the layout as separate first-screen blocks.
  • Keep ../../apps/platform/app/Filament/Widgets/Tenant/TenantTriageArrivalContinuity.php as a conditional contextual strip when arrival metadata exists; it stays secondary and must not displace the new decision-first hierarchy.
  • Prefer native Filament actions, stats, and shared badge primitives. Use local Blade and Tailwind card markup only for the bounded composite dashboard layout where native widget composition is too rigid for the new main/aside hierarchy.
  • Retain one dominant next action per card. Governance decisions remain primary, while output or diagnostics links stay secondary and capability-gated.
  • Keep any state that must survive Livewire interactions on public/query/session-backed properties; do not reintroduce private state ownership for filter or disclosure paths.

RBAC / Policy Fit

  • Tenant dashboard access remains in the tenant/admin plane under /admin/t/{tenant}. Workspace membership and tenant entitlement stay non-negotiable 404 boundaries.
  • Reuse the current tenant access model (canAccessTenant(...)), current capability registry in ../../apps/platform/app/Support/Auth/Capabilities.php, and current UI enforcement helpers rather than adding dashboard-local role or capability strings.
  • Canonical follow-up surfaces reached from the dashboard stay capability-first. Governance Inbox remains an admin-plane canonical page but supports tenant-prefilter continuity and workspace-safe access checks.
  • If a dashboard viewer may read the dashboard but lacks a follow-up capability, the summary may remain visible while the action becomes hidden or explicitly unavailable. The dashboard must not surface a clickable dead-end CTA.
  • No new destructive action or owner-only danger-zone shortcut is planned for the dashboard shell.

Data & Query Fit

UI / Surface Guardrail Plan

  • Guardrail scope: changed surfaces
  • Native vs custom classification summary: mixed
  • Shared-family relevance: dashboard signals, status messaging, action links, header actions, navigation entry points, evidence/report viewers
  • State layers in scope: shell, page, URL-query
  • Audience modes in scope: operator-MSP, manager, owner, support-platform
  • Decision/diagnostic/raw hierarchy plan: decision-first, diagnostics-second, support-raw-third
  • Raw/support gating plan: collapsed and capability-gated on follow-up surfaces only
  • One-primary-action / duplicate-truth control: the recommended-actions card owns the dominant next action; supporting cards may expose at most one reinforcing link and must not restate the same blocker at equal priority
  • Handling modes by drift class or surface: review-mandatory
  • Repository-signal treatment: review-mandatory
  • Special surface test profiles: global-context-shell
  • Required tests or manual smoke: functional-core, state-contract, bounded-browser-smoke
  • Exception path and spread control: existing dashboard-shell action-surface exemption may remain unless the final implementation explicitly retires it in feature scope
  • Active feature PR close-out entry: Guardrail / Smoke Coverage

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes
  • Systems touched: TenantDashboard, current dashboard widgets, GovernanceInbox, canonical Operations, findings and finding-exception resources, required-permissions builders and links, customer review workspace, tenant review, review-pack, evidence snapshot, localization copy, and shared badge rendering
  • Shared abstractions reused: TenantGovernanceAggregateResolver, BackupHealthDashboardSignal, RestoreSafetyResolver, OperationRunLinks, RequiredPermissionsLinks, TenantRequiredPermissionsViewModelBuilder, existing review/evidence/review-pack resources, BadgeRenderer, and current capability helpers
  • New abstraction introduced? why?: one bounded tenant-dashboard summary query/view-model layer to unify existing widget-local truth, action priority, and fallback behavior for this page only
  • Why the existing abstraction was sufficient or insufficient: current shared domain seams are sufficient, but the current vertical widget composition is insufficient for a calm decision-first first screen because priority, reason, and impact remain fragmented across widgets
  • Bounded deviation / spread control: the new summary layer remains tenant-dashboard-local, derived, and replace-before-layered. It must not become a generic dashboard framework or a second status taxonomy

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: yes
  • Central contract reused: canonical operations page plus OperationRunLinks, and any existing review-pack generation start surface if reused
  • Delegated UX behaviors: tenant-safe URL resolution, canonical operations collection links, row or detail links for recent runs, and any existing queued toast or terminal notification behavior only through already shipped start paths
  • Surface-owned behavior kept local: the dashboard chooses whether to surface a pure navigation CTA or an existing start-capable action; it does not own lifecycle transitions, queued DB notifications, or dedupe logic
  • Queued DB-notification policy: existing shared policy only
  • Terminal notification path: central lifecycle mechanism on the reused start path; not applicable for pure navigation links
  • Exception path: none planned

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: no
  • Provider-owned seams: existing required-permissions view model and required-permissions links only
  • Platform-core seams: tenant dashboard summary, governance posture, operations continuity, and output-readiness composition
  • Neutral platform terms / contracts preserved: workspace, tenant, provider, operation, review, evidence, review pack, governance, required permissions
  • Retained provider-specific semantics and why: provider display names may remain visible inside compact provider-health copy because they reflect the current tenant context, but deeper provider detail stays in existing provider-owned follow-up surfaces
  • Bounded extraction or follow-up path: none

Constitution Check

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

  • Inventory-first / snapshot truth: PASS. The dashboard consumes existing tenant-scoped observed state, review, evidence, and operation truth without changing source-of-truth ownership.
  • Read/write separation: PASS. The slice is read-mostly. Any reused existing mutation-capable action must keep current preview, confirmation, audit, and OperationRun behavior.
  • Graph contract path: PASS. No new Graph calls or contract-registry work are planned.
  • Deterministic capabilities: PASS. Existing capability registry and current authorization helpers remain authoritative.
  • RBAC-UX plane separation: PASS. The feature remains in the tenant/admin plane with allowed canonical admin follow-up routes only; no /system surface is introduced.
  • Workspace and tenant isolation: PASS. Workspace membership and tenant entitlement remain 404 boundaries, and canonical admin destinations stay tenant-prefiltered when opened from the dashboard.
  • Destructive confirmation standard: PASS by non-use. No new destructive dashboard action is in scope.
  • Global search safety: PASS. No new globally searchable resource or search scope is introduced.
  • OperationRun / Ops-UX: PASS. Recent-run and existing start-action continuity reuse the current central operations UX seams rather than composing local run lifecycle behavior.
  • Data minimization: PASS. Raw JSON, logs, provider dumps, and support diagnostics remain secondary or gated.
  • Test governance (TEST-GOV-001): PASS. Planned proof stays in focused feature suites plus one explicit browser smoke.
  • Proportionality / no premature abstraction: PASS. One bounded summary layer is justified because current widget-local composition cannot produce the required decision-first hierarchy safely or clearly.
  • Persisted truth (PERSIST-001): PASS. No new table, cached projection, or persisted dashboard artifact is planned.
  • Behavioral state (STATE-001): PASS. Fallback and availability states remain derived presentation semantics only.
  • UI semantics / shared pattern first / Filament-native UI: PASS. Shared badge semantics, shared links, and native Filament or bounded custom card surfaces remain the default path.
  • Provider boundary (PROV-001): PASS. The slice reuses provider-owned follow-up seams without widening provider-specific contracts.
  • Filament / Laravel planning contract: PASS. Filament stays on Livewire v4, provider registration remains in ../../apps/platform/bootstrap/providers.php, no new panel is added, no global-searchable resource is introduced, and no new asset bundle is planned.

Gate evaluation: PASS.

  • The feature remains a bounded productization pass over the existing tenant dashboard route and downstream repo-real surfaces.
  • The only planned structural addition is a dashboard-local derived summary composition layer justified by current release truth.
  • No constitution blocker remains unresolved after repo discovery.

Post-design re-check: PASS (design artifacts: research.md, data-model.md, quickstart.md, contracts/tenant-dashboard-productization.openapi.yaml).

Test Governance Check

  • Test purpose / classification by changed surface: Feature for summary scoping, action priority, fallback honesty, route continuity, and capability gating; Browser for one bounded tenant landing smoke
  • Affected validation lanes: confidence, browser
  • Why this lane mix is the narrowest sufficient proof: the repo already has tenant dashboard rendering, truth-alignment, scope, and RBAC tests. Adding focused dashboard productization tests plus one explicit smoke is cheaper and more honest than widening browser or heavy-governance families
  • Narrowest proving command(s):
    • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Dashboard/TenantDashboardProductizationSummaryTest.php tests/Feature/Dashboard/TenantDashboardProductizationActionsTest.php tests/Feature/Dashboard/TenantDashboardProductizationAuthorizationTest.php tests/Feature/Dashboard/TenantDashboardProductizationReadinessTest.php
    • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardDbOnlyTest.php tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php tests/Feature/Filament/TenantDashboardTenantScopeTest.php tests/Feature/Filament/TenantDashboardArrivalContextTest.php tests/Feature/Filament/TenantDashboardArrivalContextPerformanceTest.php tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
    • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php
    • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • Fixture / helper / factory / seed / context cost risks: moderate but contained; reuse existing workspace selection, tenant entitlement, findings, exception, review, evidence, review-pack, operation-run, and arrival-context fixtures instead of adding provider HTTP or queue-heavy defaults
  • Expensive defaults or shared helper growth introduced?: no; any new factory or helper should stay explicit and dashboard-local
  • Heavy-family additions, promotions, or visibility changes: one new browser smoke file only; no new heavy-governance family
  • Surface-class relief / special coverage rule: global-context-shell with standard-native Filament relief on downstream reused resources
  • Closing validation and reviewer handoff: rerun the commands above, verify the header-action cap, KPI cap, and recommended-action cap, verify canonical operations and governance inbox tenant-prefilter continuity, verify provider/risk/output fallback honesty, verify no raw JSON or log panel is default-visible, and verify the overview remains usable at a common narrow-width viewport without horizontal scrolling or losing the decision-first hierarchy
  • Budget / baseline / trend follow-up: none expected beyond a small feature-local increase in dashboard assertions
  • Review-stop questions: lane fit, hidden fixture growth, browser sprawl, duplicate-truth regressions, action-density regressions
  • Escalation path: document-in-feature for contained dashboard-shell exemption notes; reject-or-split for any drift into persistence, new frameworkization, or widened browser scope
  • Explicit review outcome: document-in-feature because the planned browser addition stays feature-local and bounded, and the current dashboard-shell exception remains contained within this spec unless implementation drifts into the escalation path above
  • Active feature PR close-out entry: Guardrail / Smoke Coverage
  • Why no dedicated follow-up spec is needed: this plan already captures the bounded dashboard productization slice; later inbox, portal, or localization expansion stays outside this feature

Project Structure

Documentation (this feature)

specs/266-tenant-dashboard-productization-v1/
├── checklists/
│   └── requirements.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── tenant-dashboard-productization.openapi.yaml
└── tasks.md             # Created later by /speckit.tasks, not by this plan step

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── TenantDashboard.php
│   │   │   ├── Governance/GovernanceInbox.php
│   │   │   ├── Monitoring/Operations.php
│   │   │   └── Reviews/CustomerReviewWorkspace.php
│   │   ├── Widgets/
│   │   │   ├── Dashboard/
│   │   │   └── Tenant/
│   │   └── Resources/
│   │       ├── FindingExceptionResource.php
│   │       ├── TenantReviewResource.php
│   │       ├── ReviewPackResource.php
│   │       └── EvidenceSnapshotResource.php
│   ├── Services/
│   │   └── Intune/TenantRequiredPermissionsViewModelBuilder.php
│   └── Support/
│       ├── Baselines/TenantGovernanceAggregateResolver.php
│       ├── BackupHealth/
│       ├── Links/RequiredPermissionsLinks.php
│       ├── RestoreSafety/
│       ├── OperationRunLinks.php
│       └── CustomerHealth/
├── bootstrap/providers.php
├── resources/views/filament/widgets/dashboard/
├── lang/
│   ├── de/localization.php
│   └── en/localization.php
└── tests/
    ├── Browser/Dashboard/
    ├── Feature/Dashboard/
    ├── Feature/Filament/
    └── Feature/Rbac/

Structure Decision: Laravel monolith. The implementation stays inside the existing apps/platform tenant dashboard, downstream tenant/admin follow-up routes, localization files, and focused dashboard tests. No new panel, provider, persistence, or standalone frontend structure is introduced.

Complexity Tracking

Violation Why Needed Simpler Alternative Rejected Because
One bounded dashboard summary query/view-model layer Current widget-local logic cannot express one ordered tenant posture, one top action list, and one honest fallback model without duplicating or scattering truth Pure copy or spacing polish would leave priority fragmented across the current widget stack and would not satisfy the decision-first contract

Proportionality Review

  • Current operator problem: the current tenant landing page exposes truthful building blocks but forces operators to reconstruct posture and next action from separate widgets, tables, and utilities.
  • Existing structure is insufficient because: the current widget stack is optimized for local truth slices, not for one coherent first-screen decision contract. Coordinating those widgets directly would keep priority duplicated and brittle.
  • Narrowest correct implementation: one dashboard-local derived summary composition plus one composite overview surface that reuses existing domain seams, links, and badge semantics.
  • Ownership cost created: limited dashboard-local maintenance and regression coverage around priority rules, fallback honesty, and route continuity; no migration or persistence cost.
  • Alternative intentionally rejected: a new persisted dashboard aggregate or generic dashboard framework was rejected because the problem is productized composition of existing truth, not missing domain storage or a reusable platform dashboard engine.
  • Release truth: current-release truth.

Phase 0 — Research (output: research.md)

Research resolves the implementation-shaping decisions for the smallest safe dashboard productization slice:

  • keep the existing TenantDashboard route as the canonical tenant landing surface
  • retain arrival-context continuity as a thin conditional strip rather than a first-screen dominant block
  • consolidate current widget-local truth behind one bounded dashboard summary layer instead of inventing new persistence or a generic framework
  • use the existing tenant-prefilter-capable Governance Inbox as the primary canonical governance queue candidate
  • use existing findings, risk-exception, required-permissions, review, evidence, review-pack, and operations surfaces as the only follow-up targets
  • keep provider health anchored to required-permissions truth because no dedicated tenant provider-health page is required for this slice
  • reuse existing copy and badge semantics rather than inventing a dashboard-specific score vocabulary
  • keep tests bounded to the existing tenant dashboard feature family plus one explicit browser smoke

Output: research.md

Phase 1 — Design (outputs: data-model.md, contracts/, quickstart.md)

Design artifacts capture the narrow productization shape:

  • no new persistence; existing tenant-owned findings, exceptions, operation runs, review packs, evidence snapshots, tenant reviews, and recovery evidence remain authoritative
  • one derived TenantDashboardSummary contract documents the page-level composition without becoming stored truth
  • conceptual route and view contracts document the existing dashboard, governance inbox, operations, findings, risk-exception, permissions, review, evidence, and review-pack entry points reused by the implementation
  • quickstart records implementation order, exact proving commands, Filament v5 / Livewire v4 posture, provider-registration location, global-search non-impact, destructive-action non-impact, and unchanged asset strategy

Artifacts:

Phase 2 — Planning (for tasks.md)

Dependency-ordered implementation outline for the later tasks.md step:

  1. Refactor the tenant dashboard shell so the page exposes one composite decision-first overview surface plus conditional arrival continuity.
  2. Build the bounded dashboard summary query/view-model from existing findings, risk-exception, governance aggregate, recovery, required-permissions, review, evidence, pack, and operations truth.
  3. Recompose the first-screen hierarchy into top context, capped header actions, capped KPI cards, recommended next actions, governance status rows, recent operations, and aside readiness cards.
  4. Wire all follow-up actions to existing repo-real routes only, preserving tenant-prefilter continuity and capability-safe hidden or unavailable states.
  5. Demote support utilities out of the primary header plane if they survive the productization pass, while preserving their existing capability gates and behavior.
  6. Expand the focused tenant dashboard feature tests and add one bounded browser smoke for the productized landing flow.

Planning Guardrail Notes

  • Planning guardrail result: PASS. Filament remains v5 on Livewire v4, provider registration remains in ../../apps/platform/bootstrap/providers.php, no new global-search scope is introduced, no new destructive dashboard action is planned, and asset handling stays unchanged (cd apps/platform && php artisan filament:assets remains deploy-only if future registered assets are ever added).
  • Shared seam result: the plan stays on existing dashboard, governance, review, permissions, and operations seams instead of inventing a second dashboard language or new persistence.
  • Output-readiness result: customer-safe output stays anchored to existing review, evidence, and review-pack surfaces; no fake Open customer view route is planned.
  • Provider-health result: current tenant required-permissions truth is the real follow-up surface; no speculative tenant provider-health page is assumed.
  • Agent context update: run after artifact generation; no new technology is expected to be added beyond the existing Laravel/Filament stack.

Implementation Close-Out Notes

  • Dashboard Productization v1 is an operator-facing tenant landing surface. It improves decision-first triage and governance follow-up without claiming a customer-facing workspace is complete.
  • Customer-safe review consumption remains follow-up work for Customer Review Workspace v1. The dashboard may link to existing repo-real review and export surfaces, but it must not imply that a broader customer handoff workspace is finalized.
  • Mixed German and English operator copy is consciously left open in this slice. Full copy harmonization remains follow-up work for Localization v1.