Skip to main content

UX-AUDIT-LEDGER-EXPLORER.md

This document defines the UX contract for a cross-entity audit and ledger explorer.

Goal:

  • make forensic navigation fast for operators and auditors
  • keep append-only truth visible without exposing internal implementation noise
  • support pivoting across compliance, engagement, submission, claims, and disputes evidence trails

Capability Baseline (Validated 2026-02-25)​

Backend-live now (multi-source audit surfaces):

  • compliance ledger:
    • GET /api/v1/compliance/ledger
  • compliance jobs and retention incidents:
    • GET /api/v1/compliance/jobs
    • GET /api/v1/compliance/retention-incidents
  • engagement timeline/events:
    • GET /api/v1/engagements/\{id\}/timeline
    • POST /api/v1/engagements/\{id\}/events
  • glass box lenses:
    • GET /api/v1/glass-box/assignments/\{id\}
    • GET /api/v1/glass-box/submissions/\{id\}
    • GET /api/v1/glass-box/engagements/\{id\}
  • claims/disputes event trails:
    • GET /api/v1/claims/\{id\}/events
    • GET /api/v1/disputes/\{id\}/events

Current backend limitation:

  • no single unified "all-events" endpoint exists yet.
  • explorer must federate/pivot across the existing read surfaces.

0. Explorer Doctrine (MUST)​

  1. Audit explorer is read-first by default; writes happen in domain screens.
  2. Every row must answer: who, what, when, where, why.
  3. Event rows are immutable representations; corrections are new rows, never edits.
  4. Cross-entity pivots must preserve filters and timeline anchor.
  5. Redaction and capability boundaries apply before rendering details.

0.1 Explorer Interface Guardrails (MUST)​

  • Dense audit tables must remain keyboard-complete with predictable focus and row navigation.
  • Filter state must be URL-addressable and restorable without losing timeline context.
  • Event detail drawers must preserve provenance semantics and redaction behavior in plain language.
  • Export/download actions must produce accessible output formats with preserved structure and metadata labels.
  • Mobile/iPad supports scoped lookup and event inspection; deep cross-entity forensics may be desktop-optimized with explicit handoff.
  • UI must never imply mutability of ledger rows; corrective workflows are linked actions to domain surfaces only.

1. Information Architecture​

Place under Governance > Audit Explorer.

Primary tabs:

  1. Compliance Ledger
  2. Engagement Timelines
  3. Submission Forensics
  4. Claims and Disputes

Supporting surfaces:

  • right drawer for event metadata and context references
  • deep links to domain pages (Submission, Engagement, Claim, Dispute)

2. Global Filters and Query Model​

Global filters (persist across tabs):

  • tenant-scoped time range
  • subject ID
  • event type
  • actor user ID (where available)
  • limit/page

UX rules:

  • filter state is URL-addressable.
  • switching tabs preserves shared filters where valid.
  • each tab shows active filter chips and provides one-click clear.

3. Tab Contracts​

3.1 Compliance Ledger​

Source:

  • GET /api/v1/compliance/ledger?subjectId=&limit=

Required columns:

  • created at
  • event type
  • subject ID
  • metadata preview

Actions:

  • Open event details
  • Copy subject ID
  • Pivot to subject (submission/engagement/claim/dispute where possible)

3.2 Engagement Timelines​

Source:

  • GET /api/v1/engagements/\{id\}/timeline

Required columns:

  • occurred at
  • source
  • event type
  • submission ID (if present)
  • actor user ID (if present)

Actions:

  • Open engagement
  • Open submission
  • Open event details

3.3 Submission Forensics​

Source:

  • GET /api/v1/glass-box/submissions/\{id\}

Required sections:

  • submission summary
  • immutable snapshot references
  • amendments/verification context
  • readiness and KOE block (capability-redacted where required)

Actions:

  • Open full submission
  • Copy forensic link
  • Open related engagement

3.4 Claims and Disputes​

Sources:

  • GET /api/v1/claims/\{id\}/events
  • GET /api/v1/disputes/\{id\}/events

Required columns:

  • occurred at
  • event type
  • actor
  • payload summary

Actions:

  • Open claim/dispute
  • Open event payload

4. Row and Drawer Contract​

Every audit row opens a standard drawer with:

  • canonical timestamp (UTC + localized display)
  • event type and source
  • actor (if present)
  • subject identifiers
  • metadata JSON viewer (collapsed by default)
  • context links to related entities

Drawer rules:

  • preserve scroll and selection in table when closed
  • support keyboard navigation and copy-friendly fields

5. Redaction and Capability Rules​

  1. Capability gating
  • hide tabs user cannot access.
  • if a row references an inaccessible entity, render plain text with "No permission" tooltip.
  1. Glass box redaction
  • when link-principal/external scopes apply, hide sensitive readiness reasons and personal data.
  1. Safe metadata rendering
  • treat unknown metadata keys as display-only JSON.
  • never execute/render HTML from payload fields.

6. Federation Behavior (No Unified Endpoint Yet)​

Until a unified backend endpoint exists, explorer behavior is:

  1. start from a chosen lens (compliance, engagement, submission, claim/dispute)
  2. render lens-native rows
  3. offer explicit pivots to other lenses via entity IDs

UX requirement:

  • show a lens badge on each row so users understand provenance of the displayed event.

7. Target-State Backend Enhancements (Tracked)​

  1. Unified audit query endpoint with typed source facets.
  2. Cursor-based incremental timeline fetch for large windows.
  3. Signed export artifact for filtered result sets.
  4. Multi-entity query (subjectIds[]) for incident review workflows.

These are not required to launch first explorer UX, but they are required for enterprise-scale forensic throughput.

8. Definition of Done​

  1. Audit explorer provides federated views over compliance, engagement, submission, and claims/disputes event surfaces.
  2. Global filters are stable and URL-addressable.
  3. Every row has a consistent details drawer with pivot actions.
  4. Capability and redaction boundaries are explicit and testable.
  5. Federation behavior is documented so frontend does not assume a non-existent unified endpoint.