Ahmed Darrazi 9752e5e90e spec: add 002 filament json

2025-12-14 19:56:17 +01:00

13 KiB

Raw Blame History

Implementation Plan: Filament JSON UI for Policy Views

Branch: tenantpilot-v1 | Date: 2025-12-13 | Spec: spec.md Input: Feature specification from /specs/002-filament-json/spec.md

Summary

Improve readability of policy snapshots and settings in the admin UI by integrating pepperfm/filament-json:^4 as a read-only JSON viewer component. Primary target is the Policies → View Policy page where raw JSON is currently hard to scan. This is a UI-only feature with no changes to sync, backup, restore logic, or Graph integration.

Key deliverables:

JSON viewer component (fold/collapse, search, copy) on Policy View page
Large payload handling (warnings, truncation, optional download)
Preserve existing table views where appropriate (Settings Catalog)
Tab-based UI: Settings (table) + JSON (viewer)
Read-only display with no behavioral changes

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies:

Laravel 12
Filament 4
Livewire 3
pepperfm/filament-json:^4 (to be installed)

Storage: PostgreSQL (existing, no schema changes)
Testing: Pest 4 (feature + browser tests)
Target Platform: Web (Laravel Sail locally, Dokploy deployment)
Project Type: Web application (Laravel + Filament admin panel)
Performance Goals:

Render JSON up to 500 KB inline without freezing
Large payloads (>500 KB) show warning + collapsed by default
No additional Graph API calls

Constraints:

Read-only viewer (no editing/saving)
Tenant-scoped (all actions respect current tenant context)
No horizontal overflow beyond card bounds
Must preserve existing Settings Catalog table functionality

Scale/Scope:

Single page modification: Policy View (PolicyResource ViewRecord)
Optional: Policy Versions View (raw JSON section only)
~3-5 Filament infolist entries/components
Asset publishing: document if public/vendor/ assets must be committed

Constitution Check

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

I. Safety-First Design

✅ PASS: Read-only viewer, no destructive actions
✅ PASS: No changes to backup/restore/sync logic (FR-040)
✅ PASS: Large payload warnings prevent browser freeze (FR-038, NFR-036.1)

II. Immutable Versioning

✅ PASS: No changes to versioning or snapshot storage
✅ PASS: Viewer displays existing snapshot data only (NFR-036.4)

III. Defensive Restore

✅ PASS: No restore flow changes

IV. Auditability

✅ PASS: No new audit requirements (FR-040)
✅ PASS: Copy/download actions use existing tenant-scoped records (NFR-036.3)

V. Tenant-Aware Architecture

✅ PASS: All UI operates within tenant context (NFR-036.3)
✅ PASS: No cross-tenant data exposure

VI. Graph Abstraction

✅ PASS: No new Graph calls (FR-040)
✅ PASS: No token storage changes

VII. Spec-Driven Development

✅ PASS: Spec complete with 6 FRs, 3 user stories, 7 success criteria
✅ PASS: Exclusions documented (no global refactor, no editor mode)

GATE STATUS: ✅ ALL GATES PASS — Proceed to Phase 0

Project Structure

Documentation (this feature)

specs/002-filament-json/
├── plan.md              # This file
├── research.md          # Phase 0: Package compatibility, asset publishing, integration patterns
├── data-model.md        # Phase 1: N/A (no schema changes)
├── quickstart.md        # Phase 1: Installation, usage examples
├── contracts/           # Phase 1: N/A (no API contracts)
└── tasks.md             # Phase 2: Task breakdown (created by /speckit.tasks)

Source Code (repository root)

app/
├── Filament/
│   └── Resources/
│       └── PolicyResource/
│           └── Pages/
│               └── ViewPolicy.php        # Primary modification target
├── View/
│   └── Components/
│       └── JsonViewer.php                # Optional: Blade component wrapper (if needed)

resources/
└── views/
    └── filament/
        └── resources/
            └── policy-resource/
                └── pages/
                    └── view-policy.blade.php   # If custom view needed

tests/
├── Feature/
│   └── Filament/
│       └── PolicyResourceViewTest.php    # Feature tests for Policy View UI
└── Browser/
    └── PolicyJsonViewerTest.php          # Pest 4 browser tests

config/
└── (no changes expected)

database/
└── (no changes - UI only)

public/
└── vendor/
    └── filament-json/                    # May appear after asset publishing
        └── (CSS/JS assets)

Structure Decision: Laravel web application with Filament admin panel. Modifications are scoped to:

app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php (primary)
Optional custom Blade views if Filament infolist schema is insufficient
Tests in tests/Feature/Filament/ and tests/Browser/

No database migrations, no new models, no service layer changes.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
(none)	(none)	(none)

Justification: All constitution gates pass. This is a low-risk UI enhancement with no architectural deviations.

Phase 0: Research & Prerequisites

Goal: Resolve all NEEDS CLARIFICATION items and gather integration patterns.

Research Tasks

Package Compatibility
- ✅ Verify pepperfm/filament-json:^4 is Filament 4 compatible
- ✅ Check if it supports infolists (read-only views) vs. forms
- ✅ Identify available features: fold/collapse, search, copy, line numbers
Asset Publishing
- ✅ Determine if php artisan filament:assets or similar is required
- ✅ Check if published assets should be committed or generated during deployment
- ✅ Test if assets work without explicit publishing (auto-serve from vendor)
Integration Patterns
- ✅ Find best practice for adding JSON viewer to Filament infolist
- ✅ Identify how to implement tabs (Settings table + JSON viewer)
- ✅ Determine payload size detection method (string length, JSON byte count)
Large Payload Handling
- ✅ Establish truncation strategy (client-side vs. server-side)
- ✅ Identify safe download mechanism (streaming response, tenant-scoped)
Testing Strategy
- ✅ Confirm Pest 4 browser tests can interact with Filament infolists
- ✅ Check if Livewire testing helpers cover tab switching

Output: research.md with decisions, alternatives, and example code snippets.

Phase 1: Design & Contracts

Prerequisites: Phase 0 research complete

Design Artifacts

Data Model (data-model.md)
- N/A — No schema changes. Document that feature uses existing Policy model's snapshot column.
API Contracts (contracts/)
- N/A — No API endpoints. UI-only feature.
Quickstart Guide (quickstart.md)
- Installation: composer require pepperfm/filament-json:^4
- Asset publishing (if required): php artisan vendor:publish --tag=filament-json-assets
- Usage example: How to add JSON viewer to PolicyResource ViewPolicy page
- Configuration: Payload size thresholds (500 KB soft limit)
- Testing: Run ./vendor/bin/pest --filter=PolicyJsonViewer
Component Design
- Filament infolist entry: ViewEntry::make('snapshot') with custom view rendering pepperfm/filament-json component
- Tab structure: Tabs::make() with Tab::make('Settings') and Tab::make('JSON')
- Payload size check: strlen(json_encode($record->snapshot)) > 512000 (500 KB)
- Warning badge: Filament Badge::make() with warning color

Output:

quickstart.md: Installation, usage, testing
data-model.md: Brief note that no schema changes are needed
Updated agent context (if new technology added)

Phase 2: Task Breakdown

Output: tasks.md (created by /speckit.tasks command, NOT by /speckit.plan)

Anticipated Task Categories

Setup & Dependencies (1-2 tasks)
- Install pepperfm/filament-json:^4
- Publish assets (if required) and document process
Policy View UI Modification (3-5 tasks)
- Add JSON viewer component to ViewPolicy infolist
- Implement tabs: Settings (table) + JSON (viewer)
- Add large payload detection + warning badge
- Implement copy-to-clipboard action
- Optional: Add "Download JSON" action for large payloads
Styling & Layout (2-3 tasks)
- Prevent horizontal overflow
- Ensure monospace font, line wrapping
- Match Filament section padding/spacing
- Test dark mode compatibility
Testing (3-4 tasks)
- Feature test: Verify JSON viewer renders with snapshot data
- Feature test: Large payload shows warning, no freeze
- Browser test: Tab switching works (Pest 4)
- Browser test: Copy button populates clipboard
Documentation (1-2 tasks)
- Update README.md or in-app help (if applicable)
- Document asset publishing in deployment notes
Validation (1 task)
- Run ./vendor/bin/pest and ./vendor/bin/pint --dirty
- Verify no backup/restore test failures (SC-005)

Estimated Complexity: 10-15 tasks total

Constitution Check (Post-Design)

Re-evaluate after Phase 1 design is complete.

Design Compliance Review

✅ Safety-First: Read-only viewer, large payload warnings implemented
✅ Immutable Versioning: No changes to snapshot storage or versioning logic
✅ Defensive Restore: No restore flow modifications
✅ Auditability: No new audit requirements; tenant-scoped actions preserved
✅ Tenant-Aware: All UI respects current tenant context
✅ Graph Abstraction: No new Graph calls or token management
✅ Spec-Driven: Design artifacts align with spec (FR-036 to FR-041, NFR-036.1 to NFR-036.5)

POST-DESIGN GATE STATUS: ✅ ALL GATES PASS

Implementation Sequence

Phase 0 (Research):
- Run research agents for package compatibility, asset publishing, integration patterns
- Consolidate findings in research.md
Phase 1 (Design):
- Create quickstart.md with installation/usage examples
- Document payload size thresholds and tab structure
- Update agent context (if needed)
Phase 2 (Task Generation):
- Execute /speckit.tasks to generate tasks.md
- Review task breakdown for completeness (FR coverage, NFR validation)
Phase 3 (Implementation) (outside of /speckit.plan scope):
- Execute tasks sequentially
- Run tests after each UI modification
- Validate no existing functionality breaks
Phase 4 (Validation) (outside of /speckit.plan scope):
- Full test suite: ./vendor/bin/pest
- Code style: ./vendor/bin/pint --dirty
- Manual QA: Large payloads, tab switching, copy actions
- Deploy to Staging, validate before Production

Risks & Mitigations

Risk	Impact	Mitigation
Asset publishing floods `public/`	Large commit, slow CI	Document whether to commit assets or rely on deploy build steps; test auto-serving from vendor
Browser freeze on large JSON	Poor UX	Implement 500 KB soft limit, show warning + collapsed by default (NFR-036.1)
Plugin incompatible with infolists	Blocker	Phase 0 research must confirm infolist support; fallback to custom Blade component if needed
Horizontal overflow breaks layout	UX degradation	Add CSS constraints: `max-width: 100%; overflow-wrap: break-word;` (NFR-036.5)
Existing Settings Catalog table broken	Regression	Keep table as default tab, JSON as secondary; run existing tests (SC-005)

Success Criteria Validation

Criterion	Validation Method	Phase
SC-001: JSON viewer visible on Policy View	Feature test: `assertSee('JSON')`	Phase 3
SC-002: No content overflow	Browser test: Check card bounds	Phase 3
SC-003: Large payload warning shown	Feature test: Mock 600 KB snapshot	Phase 3
SC-004: Settings Catalog table usable	Feature test: Existing tests pass	Phase 3
SC-005: No backup/restore changes	Pest suite: All tests pass	Phase 4
SC-006: Build/CI passes	Terminal: `./vendor/bin/pest && ./vendor/bin/pint --dirty`	Phase 4
SC-007: No unintended asset commits	Git diff review	Phase 3

Definition of Done

✅ All 6 functional requirements (FR-036 to FR-041) implemented
✅ All 5 non-functional requirements (NFR-036.1 to NFR-036.5) validated
✅ 3 user stories tested (US-UI-01, US-UI-02, US-UI-03)
✅ Feature tests + Browser tests (Pest 4) passing
✅ Code style validated (./vendor/bin/pint --dirty)
✅ No regressions in backup/restore/sync tests
✅ Asset publishing documented (commit decision made)
✅ Quickstart guide complete
✅ Deployment impact assessed (Staging validation required)

Next Steps

Execute Phase 0 research tasks → Generate research.md
Execute Phase 1 design tasks → Generate quickstart.md
Run /speckit.tasks to generate task breakdown
Begin implementation following generated tasks

Branch Ready: ✅ tenantpilot-v1
Spec Complete: ✅ spec.md
Plan Complete: ✅ This file

13 KiB Raw Blame History