ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
ed66591f2e
TenantAtlas/specs/399-dashboard-inbox-table-contract/plan.md
Ahmed Darrazi ed66591f2e
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m18s
Details
feat: migrate dashboard inbox table contracts to productized flow
2026-06-22 23:04:26 +02:00

23 KiB
Raw Blame History

Implementation Plan: Spec 399 - Dashboard / Inbox / Table Contract Migration v1

Branch: 399-dashboard-inbox-table-contract | Date: 2026-06-22 | Spec: specs/399-dashboard-inbox-table-contract/spec.md Input: Feature specification from /specs/399-dashboard-inbox-table-contract/spec.md

Summary

Migrate existing /admin dashboard, inbox, and table-heavy surfaces to the Product Surface Contract introduced by Spec 395. The implementation should reduce default-visible complexity on Environment Dashboard, Workspace Overview, Governance Inbox, Findings list/inbox surfaces, Operations Hub, and directly touched hot tables. It must demote technical proof links, cap or product-paginate tables, preserve existing RBAC/audit/OperationRun behavior, and avoid any new runtime Product Surface framework.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12.52, Filament 5.2.1, Livewire 4.1.4, Pest 4.3, Tailwind CSS 4.2 through existing assets only
Storage: PostgreSQL via existing Laravel models; no schema change planned
Testing: Pest Feature/Livewire/Filament tests and Pest Browser focused smoke
Validation Lanes: confidence + browser; fast-feedback only for pure helper assertions if introduced
Target Platform: Laravel Sail locally, Dokploy container deployments for staging/production
Project Type: Laravel monolith in apps/platform with Filament admin panel at /admin
Performance Goals: no new render-time remote calls; dashboard/inbox/table default views remain DB-only where currently DB-only
Constraints: no migrations, no new persisted truth, no new Product Surface runtime framework, no completed-spec rewrites, no legacy compatibility shims
Scale/Scope: existing operator-facing /admin dashboard/inbox/table surfaces and directly touched hot tables only

UI / Surface Guardrail Plan

  • Guardrail scope: changed rendered operator-facing surfaces.
  • Affected routes/pages/actions/states/navigation/panel/provider surfaces:
    • Environment Dashboard: apps/platform/app/Filament/Pages/EnvironmentDashboard.php, apps/platform/app/Filament/Widgets/Dashboard/EnvironmentDashboardOverview.php, apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php, and related dashboard widgets if touched.
    • Workspace Overview: apps/platform/app/Filament/Pages/WorkspaceOverview.php, apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php, workspace widgets under apps/platform/app/Filament/Widgets/Workspace/.
    • Governance Inbox: apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php.
    • Findings: apps/platform/app/Filament/Resources/FindingResource.php, apps/platform/app/Filament/Resources/FindingResource/Pages/ListFindings.php, apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php, apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php where selected.
    • Operations Hub: apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/resources/views/filament/pages/monitoring/operations.blade.php, and operation widgets if touched.
    • Touched hot tables in resources/pages/widgets named by implementation discovery.
  • No-impact class, if applicable: N/A.
  • Native vs custom classification summary: mixed. Native Filament tables/actions should be used first; existing custom Blade/dashboard views may be reduced in place without inventing a parallel UI system.
  • Shared-family relevance: dashboard signals, inbox lanes, Filament tables, action surfaces, OperationRun links, technical/audit links, badges/status messaging.
  • State layers in scope: page, widget/builder payload, table state, row/bulk actions, URL-query filters where already present.
  • Audience modes in scope: operator-MSP and manager by default; support-platform only for existing technical/detail paths; no new customer-facing default path.
  • Decision/diagnostic/raw hierarchy plan: decision-first defaults, diagnostics second, raw/support technical proof hidden/collapsed/capability-gated.
  • Raw/support gating plan: collapse or demote raw proof and technical detail; keep existing authorization.
  • One-primary-action / duplicate-truth control: every touched page/section/item gets one primary action or triage path; repeated readiness/status summaries are removed or demoted.
  • Handling modes by drift class or surface:
    • Product-facing dashboard/inbox/table overload: review-mandatory and fix in feature.
    • Existing completed-spec behavior outside touched files: report-only/context.
    • Product Surface budget exception: exception-required before runtime edit continues.
    • New runtime framework/status family/persistence need: hard-stop-candidate.
  • Repository-signal treatment: default document-in-feature; escalate to follow-up-spec only for recurring table/action framework gaps outside the selected slice.
  • Special surface test profiles: standard-native-filament for native tables, monitoring-state-page for Operations Hub, global-context-shell where Workspace Overview/Governance Inbox filters or shell state are affected.
  • List-surface review checklist: docs/product/standards/list-surface-review-checklist.md must be reviewed before table/list edits and its result recorded in the implementation report.
  • Required tests or manual smoke: Feature/Livewire table and action tests, focused browser smoke, Human Product Sanity.
  • Exception path and spread control: no exceptions planned. Any exception must name the page/table, violated Product Surface rule, reason, why it remains safe, and follow-up if temporary.
  • Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
  • UI/Productization coverage decision: update coverage artifacts for each rendered surface whose default UI changes.
  • Coverage artifacts to update: docs/ui-ux-enterprise-audit/route-inventory.md and docs/ui-ux-enterprise-audit/design-coverage-matrix.md; page reports only when route/archetype/coverage classification materially changes.
  • No-impact rationale: N/A.
  • Navigation / Filament provider-panel handling: no panel provider or navigation restructure planned. If navigation links to target surfaces change visibility/prominence, record coverage artifact updates first.
  • Screenshot or page-report need: focused browser screenshots/proof required for changed rendered surfaces; full page reports are proportional only when the existing registry becomes inaccurate.

Product Surface Contract Plan

  • Product Surface Contract reference: docs/product/standards/product-surface-contract.md.
  • No-legacy posture: canonical replacement. Do not preserve old overloaded layouts, labels, default row counts, proof links, or fixtures.
  • Page archetype and surface budget plan:
    • Environment Dashboard: Dashboard Page, planned pass.
    • Workspace Overview: Dashboard Page, planned pass.
    • Governance Inbox: Inbox Page, planned pass.
    • Findings list/inbox: Inbox Page or Search/Index Page by exact host, planned pass.
    • Operations Hub: Inbox Page with technical details demoted, planned pass.
    • Touched hot tables: inherit host archetype and must satisfy table caps/action budgets unless documented exception.
  • Technical Annex and deep-link demotion plan: demote OperationRun, raw evidence, source keys, detectors, fingerprints, UUIDs, payloads, provider payloads, raw report artifacts, restore proof, and technical logs from default product hierarchy.
  • Canonical status vocabulary plan: map top-level product statuses to Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded; use allowed severities only.
  • Product Surface exceptions: none planned.
  • Browser verification plan: focused Spec 399 browser smoke over Environment Dashboard, Workspace Overview, Governance Inbox, Findings, Operations Hub, and at least one directly touched hot table.
  • Human Product Sanity plan: 5 to 15 minute review of changed surfaces, recorded in implementation report.
  • Visible complexity outcome target: decreased. Neutral is allowed only when implementation proves a larger removal on the same surface.
  • Implementation report target: specs/399-dashboard-inbox-table-contract/implementation-report.md during implementation.

Filament / Livewire / Deployment Posture

  • Livewire v4 compliance: Livewire 4.1.4 confirmed by Laravel Boost application info. No Livewire v3 APIs may be introduced.
  • Panel provider registration location: no panel provider changes planned; Laravel 12 panel providers remain in apps/platform/bootstrap/providers.php.
  • Global search posture: no global search changes planned. If a touched Resource's global search behavior is changed, implementation must update spec/plan first and ensure a safe View/Edit page plus $recordTitleAttribute, or keep global search disabled.
  • Destructive/high-impact action posture: no new destructive/high-impact actions planned. Any touched existing destructive or high-impact action must use Action::make(...)->action(...), ->requiresConfirmation(), server-side policy/gate authorization, audit logging where mutating, notification/error feedback, and Pest coverage.
  • Asset strategy: no new Filament assets planned. Use existing CSS/Blade/Filament primitives. filament:assets is not required unless implementation registers new assets, which is not expected.
  • Testing plan:
    • Feature/Livewire tests for row caps, table pagination/caps, default-hidden technical links, one primary action, and action grouping.
    • Existing surface tests updated where they assert old overloaded defaults.
    • Browser smoke over touched dashboard/inbox/table surfaces.
    • Browser or implementation-report proof for dark mode correctness, accessibility affordances, and Filament-native/shared-primitive semantics on touched custom Blade surfaces.
    • RBAC/authorization tests for any touched mutating or dangerous action.
  • Deployment impact: no env vars, migrations, queues, scheduler, storage, or assets expected.

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes.
  • Systems touched: Product Surface Contract, Filament Table UX Standard, action-surface declarations, dashboard widgets/builders, inbox page/lane builders, OperationRun link/presenter helpers, badge/status helpers, UI audit coverage artifacts.
  • Shared abstractions reused: TablePaginationProfiles, ActionSurfaceDeclaration and related action-surface guard patterns, BadgeCatalog / BadgeRenderer, UiEnforcement, WorkspaceUiEnforcement, OperationRunLinks, OperationUxPresenter, existing surface builders/presenters.
  • New abstraction introduced? why?: none planned. Small local helpers are allowed only when they reduce duplication inside a touched surface and do not become a cross-domain runtime framework.
  • Why the existing abstraction was sufficient or insufficient: existing contracts already define budgets, status vocabulary, table profiles, and action/RBAC patterns. The implementation problem is default-visible hierarchy and table/link/action demotion, not missing platform truth.
  • Bounded deviation / spread control: any page-local collapse/cap/helper must stay in the touched surface or existing domain builder and be documented in the implementation report.

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: yes, by demoting default OperationRun proof links and preserving existing operation start/completion behavior.
  • Central contract reused: OperationRunLinks, OperationUxPresenter, OpsUxBrowserEvents, OperationRunService, and the existing OperationRun lifecycle/notification path.
  • Delegated UX behaviors: queued toast, operation link, artifact link, run-enqueued browser event, dedupe/blocked/start-failure messaging, and tenant/workspace-safe URL resolution remain delegated to existing helpers.
  • Surface-owned behavior kept local: only placement/hierarchy of operation links within dashboards/inboxes/tables.
  • Queued DB-notification policy: unchanged; no new queued DB notification opt-in.
  • Terminal notification path: unchanged through central lifecycle.
  • Exception path: none planned.

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: no.
  • Provider-owned seams: existing provider-readiness/provider-connection display may be demoted if already on a touched surface, but provider credentials, Graph contracts, provider capability registry, and provider identity seams are not changed.
  • Platform-core seams: Product Surface vocabulary and operator UI labels only.
  • Neutral platform terms / contracts preserved: provider, environment, operation, evidence, finding, workspace.
  • Retained provider-specific semantics and why: Microsoft/Intune details remain only where already repo-real and required in technical/detail paths.
  • Bounded extraction or follow-up path: none planned.

Constitution Check

GATE: Must pass before implementation. Re-check after implementation discovery and before runtime UI edits if scope changes.

  • Inventory-first: pass; no Inventory truth changes.
  • Read/write separation: pass; no new writes. Existing writes/dangerous actions must keep preview/confirmation/audit/tests.
  • Graph contract path: pass; no Graph calls or contract changes.
  • Deterministic capabilities: pass; existing capability checks remain authoritative.
  • RBAC-UX: pass; UI visibility is not security, non-member 404 and member missing capability 403 semantics must remain intact.
  • Workspace isolation: pass; workspace route/filter ownership remains explicit.
  • Tenant isolation / managed-environment entitlement: pass; no cross-tenant aggregation changes.
  • Run observability: pass; no new OperationRun types or lifecycle paths.
  • OperationRun start UX: pass if existing helpers are reused; any local OperationRun UX composition is a blocker.
  • Ops-UX 3-surface feedback: pass; unchanged.
  • OperationRun lifecycle and summary counts: pass; no status/outcome/summary-count mutation planned.
  • Data minimization: pass; technical proof is demoted rather than expanded.
  • Test governance: pass with explicit confidence + browser lanes.
  • Proportionality: pass; no new persistence, abstraction, status family, taxonomy, or UI framework approved.
  • Shared pattern first: pass if existing table/action/badge/OperationRun helpers are reused.
  • Provider boundary: pass; no provider seam changes.
  • UI semantics / one truth few layers: pass; display maps existing truth directly to Product Surface vocabulary.
  • Product Surface Contract Gate: pass planned; active spec/plan/tasks name surfaces, budgets, browser proof, human sanity, no-legacy posture, and implementation-report fields.
  • Filament-native UI: pass planned; use native Filament components/shared primitives first and keep custom Blade inside existing surface conventions.
  • Action-surface discipline: pass planned; one inspect/open model, grouped destructive/bulk actions, no empty groups.
  • UI/Productization coverage: pass planned; route inventory and design matrix updates required for changed rendered surfaces.

Test Governance Check

  • Test purpose / classification by changed surface:
    • Environment Dashboard and Workspace Overview: Feature/Livewire + Browser.
    • Governance Inbox: Feature + Browser.
    • Findings table/inbox: Feature/Livewire table/action tests + Browser for selected host.
    • Operations Hub: Feature + Browser under monitoring-state-page.
    • Touched native tables: Feature/Livewire, browser only via changed host page.
  • Affected validation lanes: confidence and browser.
  • Why this lane mix is the narrowest sufficient proof: contract behavior is rendered UI plus table/action state; Feature tests prove data/action/link shape, Browser smoke proves first-viewport hierarchy and absence of runtime/console/Filament errors.
  • Narrowest proving commands:
    • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec399
    • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec399DashboardInboxTableContractMigrationSmokeTest.php
    • targeted existing Feature/Browser tests selected by implementation discovery
    • cd apps/platform && ./vendor/bin/sail pint --dirty
    • git diff --check
  • Fixture / helper / factory / seed / context cost risks: keep reuse of existing surface fixtures explicit; do not widen default factories or browser setup.
  • Expensive defaults or shared helper growth introduced?: no planned.
  • Heavy-family additions, promotions, or visibility changes: one explicit focused browser smoke; no broad browser audit.
  • Surface-class relief / special coverage rule: standard-native-filament relief for ordinary table cap tests; dashboard/inbox/Operations still require browser.
  • Closing validation and reviewer handoff: implementation report must state commands, results, browser proof, unrelated failures, Product Surface exceptions, Human Product Sanity, visible complexity outcome, and no completed-spec rewrite assertion.
  • Budget / baseline / trend follow-up: none expected; document-in-feature if browser fixture cost grows.
  • Review-stop questions: lane fit, breadth, hidden fixture cost, heavy-family risk, Product Surface exception status.
  • Escalation path: document-in-feature for contained exceptions; follow-up-spec only for structural table/action framework gaps.
  • Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
  • Why no dedicated follow-up spec is needed: this spec already owns the current dashboard/inbox/table Product Surface migration. Follow-up is only for secondary tables outside the touched slice.

Project Structure

Documentation (this feature)

specs/399-dashboard-inbox-table-contract/
├── checklists/
│   └── requirements.md
├── plan.md
├── spec.md
└── tasks.md

No data model, contracts, or quickstart are required for preparation because this feature introduces no API, persisted entity, external contract, or new runtime data model.

Source Code (repository root)

Likely implementation surfaces, subject to implementation discovery:

apps/platform/app/Filament/Pages/
├── EnvironmentDashboard.php
├── WorkspaceOverview.php
├── Governance/GovernanceInbox.php
├── Findings/MyFindingsInbox.php
├── Findings/FindingsIntakeQueue.php
└── Monitoring/Operations.php

apps/platform/app/Filament/Widgets/
├── Dashboard/EnvironmentDashboardOverview.php
├── Dashboard/RecentOperations.php
└── Workspace/...

apps/platform/app/Filament/Resources/
├── FindingResource.php
├── FindingResource/Pages/ListFindings.php
└── OperationRunResource.php

Secondary/deferred table candidates, not default implementation surfaces unless T014 records a direct narrow touch:

apps/platform/app/Filament/Resources/
├── InventoryItemResource.php
├── PolicyResource.php
├── PolicyVersionResource.php
├── ProviderConnectionResource.php
├── BackupSetResource.php
├── RestoreRunResource.php
└── StoredReportResource.php

apps/platform/resources/views/filament/
├── widgets/dashboard/environment-dashboard-overview.blade.php
├── pages/governance/governance-inbox.blade.php
└── pages/monitoring/operations.blade.php

apps/platform/tests/Feature/
apps/platform/tests/Browser/

docs/ui-ux-enterprise-audit/
├── route-inventory.md
└── design-coverage-matrix.md

Structure Decision: Use existing Laravel/Filament page, widget, resource, view, and test directories only. Do not create new base folders or runtime frameworks.

Complexity Tracking

Violation Why Needed Simpler Alternative Rejected Because
None planned N/A N/A

Proportionality Review

  • Current operator problem: dashboard, inbox, and table-heavy pages expose internal technical detail and too many actions/links/rows by default, making the next action harder to see.
  • Existing structure is insufficient because: the existing Product Surface Contract exists, but the selected runtime surfaces still need migration to its budgets and technical demotion rules.
  • Narrowest correct implementation: reduce existing surfaces and tests in place using native Filament/shared primitives first.
  • Ownership cost created: focused Feature/Browser tests and implementation-report evidence only.
  • Alternative intentionally rejected: Product Surface runtime framework, presenter/status family, persisted surface taxonomy, broad redesign, or compatibility mode.
  • Release truth: current-release productization cleanup.

Implementation Phases

Phase 0 - Discovery and target lock

  • Re-read active spec, plan, docs/product/standards/product-surface-contract.md, docs/product/standards/filament-table-ux.md, docs/ui/action-surface-contract.md, docs/ui/operator-ux-surface-standards.md, docs/filament-guidelines.md, and relevant existing specs.
  • Inspect target files and tests to decide the exact first implementation slice.
  • Record selected surfaces, untouched/deferred surfaces, and Product Surface exceptions before runtime UI edits.

Phase 1 - Table budget and action contract foundation

  • Identify every table/list section touched by the selected surfaces.
  • Apply native Filament pagination/caps, product labels, hidden technical columns, one inspect/open model, and grouped destructive/bulk actions.
  • Add or update Feature/Livewire tests before or alongside implementation.

Phase 2 - Dashboard default reduction

  • Reduce Environment Dashboard and Workspace Overview default content to one primary question, compact summary, top attention items, one next action, and demoted proof/detail links.
  • Preserve existing authorized secondary/detail paths.
  • Update Feature tests and focused browser expectations.

Phase 3 - Inbox and Findings triage reduction

  • Reduce Governance Inbox and selected Findings surfaces to prioritized work items, product row labels, severity/state/scope, and one next action.
  • Demote source/evidence/OperationRun proof links.
  • Update lane/list tests and browser smoke.

Phase 4 - Operations Hub classification and technical demotion

  • Keep Operations Hub as attention-oriented Inbox behavior with technical details demoted.
  • Preserve OperationRun detail/technical paths for authorized users.
  • Ensure operation status/progress/outcome semantics remain existing truth and no new OperationRun UX is composed locally.

Phase 5 - Coverage artifacts, browser proof, and close-out

  • Update docs/ui-ux-enterprise-audit/route-inventory.md and docs/ui-ux-enterprise-audit/design-coverage-matrix.md for changed rendered surfaces.
  • Run focused tests/browser smoke, Pint, and diff checks.
  • Complete implementation report with Product Surface fields, no completed-spec rewrite assertion, Human Product Sanity, visible complexity outcome, deployment impact, and unrelated failure triage.