TenantAtlas/specs/133-detail-page-template/plan.md

Implementation Plan: View Page Template Standard for Enterprise Detail Screens

Branch: 133-detail-page-template | Date: 2026-03-10 | Spec: spec.md Input: Feature specification from /specs/133-detail-page-template/spec.md

Summary

Standardize the four initial enterprise detail targets around one shared read-only detail-page composition contract: a summary-first header, predictable main-and-supporting layout, dedicated related-context treatment, and secondary technical detail. Reuse the repo’s existing Filament v5 sectioned infolists, centralized badge semantics, related-navigation helpers, and existing presenter patterns, while introducing a narrow shared enterprise-detail composition layer so BaselineSnapshot, BackupSet, EntraGroup, and the workspace-context OperationRun viewer stop drifting into page-specific scaffold layouts.

Technical Context

Language/Version: PHP 8.4.15 / Laravel 12
Primary Dependencies: Filament v5, Livewire v4.0+, Tailwind CSS v4
Storage: PostgreSQL via Laravel Sail; no schema change expected
Testing: Pest v4 feature and unit tests on PHPUnit 12
Target Platform: Laravel Sail web application with workspace-plane admin routes under /admin and tenant-context routes under /admin/t/{tenant}/... Project Type: Laravel monolith / Filament web application
Performance Goals: Detail pages remain DB-only at render time, keep existing bounded queries, avoid new uncontrolled polling, and de-emphasize heavy technical payloads behind secondary sections
Constraints: Preserve existing routes and resource semantics; keep authorization plane separation intact; keep non-member access as 404 and in-scope capability denial as 403; use Infolists instead of disabled edit forms; avoid a one-size-fits-all abstraction that hides domain-specific sections
Scale/Scope: One shared detail-page standard, one shared composition layer, four aligned target pages, reusable Blade or Infolist building blocks, and focused regression coverage for section order, degraded states, action placement, and permission-aware related context

Constitution Check

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

• Inventory-first: PASS — no inventory semantics change; the feature reorganizes page presentation only.
• Read/write separation: PASS — the template itself is read-only. Existing linked mutations remain governed by their existing confirmation, audit, and test rules.
• Graph contract path: PASS — no Microsoft Graph call path is added or changed.
• Deterministic capabilities: PASS — authorization and visibility continue to flow through existing capability registries and enforcement helpers.
• RBAC-UX planes and isolation: PASS — BaselineSnapshot and OperationRun remain workspace-plane detail surfaces, BackupSet and EntraGroup remain tenant-context detail surfaces, and cross-plane behavior stays deny-as-not-found.
• Workspace isolation: PASS — workspace membership remains the entry rule for workspace-scoped target pages.
• RBAC-UX destructive confirmation: PASS — no new destructive action is introduced; retained destructive actions on touched screens must keep ->requiresConfirmation().
• RBAC-UX global search: PASS — BaselineSnapshot and OperationRun are already globally searchable-disabled; BackupSet and EntraGroup already have view pages, so any existing global-search behavior remains compliant.
• Tenant isolation: PASS — tenant-owned detail pages remain tenant-scoped; related context cannot reveal inaccessible tenant records.
• Run observability: PASS / N/A — no new OperationRun is created. OperationRun detail remains a read-only consumer of existing run state.
• Ops-UX 3-surface feedback: PASS / N/A — the template standard does not add run lifecycle feedback. Existing run actions retain current Ops-UX behavior.
• Ops-UX lifecycle and summary counts: PASS / N/A — no run transitions or new summary_counts producers are introduced.
• Ops-UX guards and system runs: PASS / N/A — existing guard coverage remains relevant but unchanged in scope.
• Automation: PASS / N/A — no queued or scheduled workflow change is required.
• Data minimization: PASS — the standard only reorders existing authorized data and keeps technical detail secondary.
• Badge semantics (BADGE-001): PASS — all elevated state badges continue to use centralized badge domains and renderers.
• UI naming (UI-NAMING-001): PASS — section titles, empty states, and actions will use domain-first operator language and avoid implementation-first terms.
• Filament UI Action Surface Contract: PASS — all touched pages remain sectioned detail surfaces with predictable header actions and no new unsupported action surfaces.
• Filament UI UX-001: PASS — the design explicitly standardizes view pages around Infolists, structured sections, main-and-supporting hierarchy, badge consistency, and explicit empty states.
• Filament v5 / Livewire v4 compliance: PASS — the feature stays inside the existing Filament v5 / Livewire v4 stack.
• Provider registration (bootstrap/providers.php): PASS — no new panel or provider is added; existing panel registration remains in bootstrap/providers.php.
• Global search resource rule: PASS — BaselineSnapshot global search remains disabled, BackupSet and EntraGroup already have view pages, and OperationRun global search remains disabled.
• Asset strategy: PASS — no heavy asset bundle is needed; existing deploy-time php artisan filament:assets behavior remains sufficient.

Project Structure

Documentation (this feature)

specs/133-detail-page-template/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── enterprise-detail-pages.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   └── Operations/
│   │       └── TenantlessOperationRunViewer.php                # MODIFY — adopt shared detail shell
│   └── Resources/
│       ├── BaselineSnapshotResource.php                        # MODIFY — align infolist contract and action-surface notes
│       ├── BaselineSnapshotResource/
│       │   └── Pages/
│       │       └── ViewBaselineSnapshot.php                    # MODIFY — adopt shared detail shell
│       ├── BackupSetResource.php                               # MODIFY — replace flat infolist with enterprise sections
│       ├── BackupSetResource/
│       │   └── Pages/
│       │       └── ViewBackupSet.php                           # MODIFY — align header actions and supporting layout
│       ├── EntraGroupResource.php                              # MODIFY — add related-context and technical-detail separation
│       ├── EntraGroupResource/
│       │   └── Pages/
│       │       └── ViewEntraGroup.php                          # MODIFY — adopt shared detail shell
│       └── OperationRunResource.php                            # MODIFY — expose shared section composition for run detail
├── Services/
│   └── Baselines/
│       └── SnapshotRendering/
│           └── BaselineSnapshotPresenter.php                  # MODIFY — map to shared summary and technical-detail slots
└── Support/
    ├── Badges/
    │   └── BadgeRenderer.php                                  # reference-only centralized badge semantics
    ├── Navigation/
    │   └── RelatedNavigationResolver.php                      # reference-only related-context assembly
    └── Ui/
        ├── ActionSurface/                                     # reference-only action contract helpers
        └── EnterpriseDetail/                                  # NEW shared detail-page composition classes/value objects/builders
resources/
└── views/
    └── filament/
        ├── infolists/
        │   └── entries/
        │       ├── related-context.blade.php                  # reference-only existing related-context partial
        │       └── enterprise-detail/                         # NEW shared summary/supporting/technical partials if needed
        └── pages/
            └── operations/                                    # reference-only current operation-run viewer Blade page
tests/
├── Feature/
│   ├── Filament/
│   │   ├── BaselineSnapshot*Test.php                          # MODIFY existing structure/degraded-state tests
│   │   ├── BackupSetEnterpriseDetailPageTest.php              # NEW detail hierarchy and action-placement coverage
│   │   ├── EntraGroupEnterpriseDetailPageTest.php             # NEW detail hierarchy and degraded-state coverage
│   │   ├── OperationRunEnterpriseDetailPageTest.php           # NEW layout and contextual-action coverage
│   │   └── EnterpriseDetailTemplateRegressionTest.php         # NEW cross-target reading-order regression coverage
│   └── Guards/
│       └── ActionSurfaceContractTest.php                      # reference-only guard coverage for changed pages
└── Unit/
    └── Support/
        └── Ui/
            └── EnterpriseDetail/                              # NEW page-composition and section-visibility tests

Structure Decision: Keep the feature inside the existing Laravel/Filament monolith. Introduce a narrow shared composition layer under app/Support/Ui/EnterpriseDetail and shared Blade or Infolist partials under resources/views/filament/infolists/entries/enterprise-detail, while refactoring the four target detail surfaces in place rather than creating a new panel, new data model, or standalone page system.

Complexity Tracking

No Constitution Check violations. No justifications needed.

Violation	Why Needed	Simpler Alternative Rejected Because
—	—	—

Phase 0 — Research (DONE)

Output:

• specs/133-detail-page-template/research.md

Key findings captured:

• The repo already has reusable building blocks for badge semantics, related-context assembly, action-surface declarations, and sectioned Infolists, but it does not yet have a shared main-and-supporting enterprise detail builder.
• BaselineSnapshot already uses a presenter-driven, sectioned view, making it the strongest reference for the standard.
• BackupSet and EntraGroup still expose flatter view-page structures, and OperationRun relies on a separate tenantless viewer that reuses OperationRunResource::infolist().
• The existing test suite already covers baseline snapshot rendering, operation-run Livewire behavior, related-navigation helpers, and action-surface guards, so the new standard can extend proven patterns instead of inventing a new testing approach.

Phase 1 — Design & Contracts (DONE)

Outputs:

• specs/133-detail-page-template/data-model.md
• specs/133-detail-page-template/contracts/enterprise-detail-pages.openapi.yaml
• specs/133-detail-page-template/quickstart.md

Design highlights:

• Define a shared enterprise detail-page read model with explicit header, main sections, supporting cards, related context, technical detail, and empty-state handling.
• Reuse existing BadgeRenderer, RelatedNavigationResolver, and page-specific presenters instead of introducing duplicate status or navigation logic.
• Apply the shared shell first to OperationRun as the operational reference implementation, then BaselineSnapshot, BackupSet, and EntraGroup.
• Keep technical metadata present but secondary, and keep domain-specific sections inside the shared structural shell.

Phase 1 — Agent Context Update (DONE)

Run:

• .specify/scripts/bash/update-agent-context.sh copilot

Phase 2 — Implementation Outline (tasks created in /speckit.tasks)

Step 1 — Introduce the shared enterprise detail composition layer

Goal: implement FR-133-01 through FR-133-05, FR-133-08, FR-133-09, FR-133-12, and FR-133-13.

Changes:

• Add a shared read model and builder contract for enterprise detail pages under app/Support/Ui/EnterpriseDetail.
• Add shared presentation partials or builder methods for summary header, supporting cards, related context, empty states, and technical-detail treatment.
• Define a reusable section taxonomy and reading-order contract that target pages can compose explicitly.

Tests:

• Add unit coverage for page composition, section visibility, technical-detail demotion, and empty-state fallback behavior.

Step 2 — Refactor OperationRun detail as the first reference implementation

Goal: implement FR-133-02 through FR-133-11 and FR-133-18 for the workspace-context run detail surface.

Changes:

• Refactor TenantlessOperationRunViewer and OperationRunResource::infolist() around the shared enterprise detail shell.
• Elevate run identity, outcome, target scope, and quick actions into the summary or supporting regions.
• Move failure and technical payload detail behind secondary sections while preserving existing contextual actions and Ops-UX rules.

Tests:

• Extend or add Livewire feature tests for summary ordering, related context, degraded target-scope states, and preserved contextual actions.

Step 3 — Refactor BaselineSnapshot detail onto the shared shell

Goal: implement FR-133-15 and reinforce FR-133-06, FR-133-07, and FR-133-11.

Changes:

• Adapt BaselineSnapshotPresenter and ViewBaselineSnapshot to emit the shared page model.
• Keep snapshot capture identity, fidelity, coverage, and governance context in the primary reading path.
• Preserve the current technical-detail section as a collapsed or secondary region inside the shared shell.

Tests:

• Reuse and extend existing BaselineSnapshot feature tests to assert summary-first structure, degraded-state handling, and related-context placement.

Step 4 — Refactor BackupSet detail onto the shared shell

Goal: implement FR-133-16 and reinforce FR-133-06 through FR-133-10.

Changes:

• Replace the current flat BackupSet infolist with structured lifecycle, scope, related-operations, and technical-detail sections.
• Keep existing mutation actions grouped and confirmation-gated where already required.
• Introduce a clearer supporting region for status, timestamps, retention or scope summary, and recent operational context.

Tests:

• Add feature coverage for summary-first rendering, related-context visibility, action placement, and low-data empty states.

Step 5 — Refactor EntraGroup detail onto the shared shell

Goal: implement FR-133-17 and reinforce FR-133-07, FR-133-08, and FR-133-11.

Changes:

• Replace the current two-section group view with a structured identity summary, classification, governance relevance, related context, and secondary provider detail treatment.
• Keep raw provider arrays or low-signal metadata in a clearly secondary technical section.

Tests:

• Add feature coverage for identity-first rendering, empty related-context behavior, and tenant-scope authorization semantics on the detail page.

Step 6 — Add cross-target regression protection and polish

Goal: implement FR-133-14, FR-133-19, FR-133-20, and FR-133-21.

Changes:

• Add cross-target regression checks proving technical detail never renders above summary content, related context remains structured, and pages do not regress into flat schema-order field walls.
• Review labels, action placement, and empty-state language against UI-NAMING-001, BADGE-001, and UX-001.

Tests:

• Add one cross-target feature regression test and any needed guard updates for the changed action surfaces.
• Run focused Sail-based Pest coverage for the four aligned pages plus relevant unit tests and existing guards.

Constitution Check (Post-Design)

Re-check result: PASS.

• Livewire v4.0+ compliance: preserved because every aligned screen remains inside the existing Filament v5 / Livewire v4 stack.
• Provider registration location: unchanged; existing panel providers remain registered in bootstrap/providers.php.
• Globally searchable resources: BaselineSnapshot is globally search disabled, BackupSet has a view page, EntraGroup has a view page, and OperationRun is globally search disabled.
• Destructive actions: no new destructive actions are introduced by the template; any retained destructive actions on touched screens continue to require confirmation and existing authorization.
• Asset strategy: no new heavy assets are planned; existing Tailwind and Filament view composition is sufficient, and deploy-time php artisan filament:assets remains unchanged.
• Testing plan: add or update focused Pest feature tests for each target page’s summary-first structure, related-context rendering, degraded-state handling, and action placement, plus unit coverage for the shared composition layer and existing action-surface guards where needed.