TenantAtlas/specs/002-filament-json/spec.md

feature	description	date	owner	branch	related_features	status
002-filament-json	Policy View UI: readable JSON + structured settings using pepperfm/filament-json (Filament v4)	2025-12-13	TenantPilot	tenantpilot-v1	001-rbac-onboarding (core v1)	draft

Spec: 002 – Filament JSON UI for Policy Views

Summary

Improve readability of policy snapshots/settings in the admin UI by using a JSON viewer/editor-style component (read-only) for places where raw JSON is currently hard to scan (especially settingsCatalogPolicy and large snapshots).

This feature is UI-only: it does not change sync, backup, restore logic, or the restore matrix. It must not introduce new Graph calls, token storage, or tenant-scope changes.

Primary implementation target:

• Policies → View Policy (first) Secondary (optional in this feature, if low-risk):
• Policy Versions → View Policy Version (Raw JSON section only)

We intend to use pepperfm/filament-json:^4 (Filament 4 compatible) to render JSON blocks elegantly (folding, search, copy, monospace, line wrapping) while keeping tables where tables are clearly better (e.g., flattened settings rows).

---

Goals

• Make Policy snapshots/settings human-readable for admins without scrolling horizontally forever.
• Provide a JSON viewer that supports:
  • folding/collapsing
  • search within JSON
  • copy-to-clipboard
  • stable monospace formatting
  • safe truncation or "large payload" handling
• Apply this primarily in Policy View (not everywhere), to keep blast radius small.

Non-Goals

• No new policy types, no changes to supported types, restore matrix, contract registry behavior.
• No new domain behavior (no diff algorithm changes, no restore logic changes).
• No new background jobs, no new persistence of normalized output.
• No replacing tables universally — only where JSON viewer clearly improves UX.

---

User Scenarios & Testing (mandatory)

User Story 1 - Admin reads policy snapshot quickly (Priority: P1)

As an admin, I can open a policy detail page and view the snapshot/settings in a readable format (foldable JSON + structured highlights), so I can understand what the policy does without digging through raw dumps.

Why this priority: Core value proposition of this feature - making existing data readable.

Independent Test: Open any policy with a captured snapshot; verify JSON viewer renders with fold/collapse + copy button.

Acceptance Scenarios:

1. Given a policy with a captured snapshot, When admin opens Policy View, Then JSON viewer renders the snapshot with fold/collapse controls.
2. Given a large policy snapshot, When admin opens Policy View, Then UI shows "Large payload" warning and collapses by default.

---

User Story 2 - Admin inspects large settings catalog policies without pain (Priority: P1)

As an admin, I can view settingsCatalogPolicy settings with both:

• a table view for quick scanning (definition/value)
• an optional JSON viewer view for deep inspection (full hydrated snapshot/settings)

Why this priority: Settings Catalog policies are the most complex and need both table + JSON representations.

Independent Test: Open a Settings Catalog policy; verify both tabs (Settings table + JSON viewer) exist and render correctly.

Acceptance Scenarios:

1. Given a settingsCatalogPolicy with hydrated settings, When admin opens Policy View, Then Settings tab shows table AND JSON tab shows full snapshot.
2. Given a settingsCatalogPolicy, When admin switches between tabs, Then no content overflow or layout break occurs.

---

User Story 3 - Admin copies a relevant JSON fragment (Priority: P2)

As an admin, I can copy JSON (whole snapshot or selected view) to share/debug safely, without secrets.

Why this priority: Enables debugging and support workflows.

Independent Test: Click copy button in JSON viewer; verify clipboard contains valid JSON.

Acceptance Scenarios:

1. Given JSON viewer is open, When admin clicks "Copy JSON", Then clipboard contains the full snapshot JSON.
2. Given a large payload with truncation, When admin clicks "Copy full JSON", Then action completes without freezing browser.

---

Edge Cases

• Snapshot missing or malformed: show "No snapshot available" or "Malformed snapshot" warning.
• Extremely large payloads (>1 MB): show warning + collapsed by default + optional download.
• Missing settings hydration (settingsCatalogPolicy): show "Settings not hydrated" hint.

Requirements (mandatory)

Functional Requirements

• FR-036: JSON viewer component on Policy View

  • Policies → View Policy MUST render the policy's snapshot/settings (where raw JSON is shown) using a read-only JSON viewer based on pepperfm/filament-json.
  • Viewer MUST support fold/collapse + search + copy.

• FR-037: Placement and scope

  • JSON viewer MUST be implemented only on Policy View for this feature.
  • Policy Versions page changes are OPTIONAL and only apply to the Raw JSON block if included.

• FR-038: Large payload handling

  • If a JSON payload exceeds thresholds (see NFRs), the UI MUST:
    • show a warning badge ("Large payload – truncated for display")
    • provide a "Copy full JSON" action only if it can be done without freezing the browser
    • otherwise "Copy truncated JSON" + "Download JSON" (optional) may be used, but download MUST be access-controlled and tenant-scoped.

• FR-039: Preserve existing table UI where it's better

  • Existing structured/tabled settings views (e.g., Settings Catalog table) SHOULD remain.
  • JSON viewer is an additional/alternative representation, preferably behind tabs:
    • Tab A: "Settings" (table/search)
    • Tab B: "JSON" (viewer)

• FR-040: No behavioral changes

  • This feature MUST NOT add Graph calls, modify restore behavior, or change snapshot capture logic.
  • No changes to audit logging schema required.

• FR-041: Asset publishing safety

  • Installing the plugin MUST NOT accidentally commit massive published assets unless explicitly intended.
  • If assets must be published, the process MUST be documented and repeatable (see NFR + Ops).

Non-Functional Requirements (Measurable)

• NFR-036.1 Performance: UI should remain responsive when rendering JSON up to:
  • 500 KB inline viewer payload (soft limit)
  • Above that: show warning + fallback (collapsed by default + optional download)
• NFR-036.2 Safety: Viewer is read-only (no editing, no save).
• NFR-036.3 Tenant isolation: Any download/copy action must operate only on the current tenant's record.
• NFR-036.4 Consistency: Viewer uses the same snapshot source as existing UI (no "different data" between table and JSON).
• NFR-036.5 Styling:
  • no horizontal overflow beyond card bounds
  • long keys/values wrap or are truncated with tooltip
  • spacing consistent with Filament sections (padding, max width)

UX Requirements

• Default view on Policy page:
  • If settings table exists (settings catalog): show table first.
  • Provide "JSON" tab for deep inspection.
• JSON viewer:
  • start collapsed for huge payloads
  • show line numbers (if supported)
  • copy button visible
• For missing settings hydration:
  • show "Settings not hydrated" warning with hint to re-sync/capture.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: On Policies → View Policy, a JSON viewer is visible and readable (fold/search/copy).
• SC-002: No content overflows the card/container.
• SC-003: For large payloads, UI shows a warning and does not freeze.
• SC-004: Existing Settings Catalog table remains usable (search works, values not cut off silently).
• SC-005: No changes in backup/restore behavior (same tests pass).
• SC-006: Build/CI passes: ./vendor/bin/pest and ./vendor/bin/pint --dirty.
• SC-007: No unintended committed asset floods (or, if committed, documented and intentional).

Exclusions (optional - only if scope needs clarification)

The following is intentionally excluded from this specification:

• Global refactor of all JSON views across the app.
• Replacing diff UI with a new viewer.
• Introducing a full "policy editor" experience.
• Changing contract registry/hydration/restore payload rules.

Risks / Notes

• Composer post-update hooks may fail locally if DB is unreachable (e.g., boost:update touching cache DB). This must not block the feature conceptually; document a safe local workflow (Sail up first or skip hook locally).
• filament:upgrade / asset publishing can overwrite public/ assets; decide explicitly whether to commit these artifacts or rely on deploy build steps.
• Plugin fit: ensure pepperfm/filament-json is compatible with Filament 4 and used in infolists / view pages (not forms) in read-only mode.

Traceability

• Implements: US-UI-01, US-UI-02, US-UI-03
• Implements: FR-036, FR-037, FR-038, FR-039, FR-040, FR-041
• NFRs: NFR-036.1, NFR-036.2, NFR-036.3, NFR-036.4, NFR-036.5