Skip to main content

📘 UX-GLASSBOX.md

This document specifies UX patterns for Glass Box: external, read-only execution visibility for clients/stakeholders/auditors via scoped links.

Goal:

  • provide trustworthy transparency without exposing control surfaces
  • keep external views simple while preserving forensic depth
  • enforce strict scope isolation and redaction rules

Capability Baseline (Validated 2026-02-25)​

Backend-live now:

  • Glass Box lenses are implemented for:
    • assignment
    • submission
    • engagement
    • programme
  • Access is via linkPrincipalAuth (no normal user session required).
  • Routes are read-only (GET only; non-GET rejected with 405 METHOD_NOT_ALLOWED).
  • Scope enforcement is strict (scopeType + exact scopeId must match path ID).
  • Submission lens includes derived koeStatus + proofReadiness with default reason redaction for link principals unless canViewReadinessReasons=true.

Current gap:

  • Frontend Glass Box screens are not yet first-class.

0. Doctrine (MUST)​

  1. Read-only by design: no write controls, no edits, no inline mutation.
  2. Scoped truth only: every view is constrained to the single scoped resource in the token.
  3. Forensic before decorative: prioritize timelines, evidence chain, and snapshot context over analytics-style decoration.
  4. External-safe defaults: redact sensitive reason detail unless link capability explicitly allows it.
  5. Clear trust signaling: show what is verified, what is not required, and what is missing without false alarms.

0.1 Glass Box Interface Guardrails (MUST)​

  • Glass Box remains strictly read-only; no control that implies mutation may be rendered.
  • Redaction state must be explicit in text; hidden reason detail is never implied to be absent evidence.
  • External-facing status language must be plain and non-ambiguous while preserving forensic meaning.
  • Timeline and scope context must be screen-reader readable and keyboard navigable.
  • Links to internal full pages are shown only when capability permits; otherwise render non-link explanatory text.
  • Mobile support is required for read/verification views; dense forensic drilldown can use progressive disclosure to avoid overload.

1. Access Model & Security UX​

Glass Box uses short-lived scoped link principal tokens (not regular user auth sessions).

Token scope fields (conceptual):

  • tenantId
  • orgUnitId
  • scopeType (ENGAGEMENT, ASSIGNMENT, SUBMISSION, PROGRAMME)
  • scopeId
  • optional visibility capability: canViewReadinessReasons

1.2 Route Invariants​

Supported routes:

  • GET /api/v1/glassbox/engagements/\{id\}
  • GET /api/v1/glassbox/assignments/\{id\}
  • GET /api/v1/glassbox/submissions/\{id\}
  • GET /api/v1/glassbox/programmes/\{id\}

Enforcement:

  • missing/invalid token -> 401 LINK_UNAUTHENTICATED
  • scope mismatch (type/id) -> 404 not_found
  • non-GET method -> 405 METHOD_NOT_ALLOWED

1.3 No Session UX Assumptions​

Do not assume:

  • in-app sidebar nav
  • account switching
  • role-driven action menus

Glass Box entry should work as a standalone page shell from a link.

2. Information Architecture​

Glass Box has four lens pages plus shared shell primitives.

Pages:

  1. Assignment Lens (/glassbox/assignments/:id)
  2. Submission Lens (/glassbox/submissions/:id)
  3. Engagement Lens (/glassbox/engagements/:id)
  4. Programme Lens (/glassbox/programmes/:id)

Shared shell:

  • minimal header (scope label + freshness timestamp)
  • read-only badge
  • optional locale selector where supported (submission lens ?lang=)

No global navigation required in v1.

3. Assignment Lens UX​

API source:

  • GET /api/v1/glassbox/assignments/\{id\}

Primary purpose:

  • cohort progress snapshot for one assignment scope.

3.1 Required Content​

  • assignment ID
  • evaluation version ID
  • run label (if present)
  • targets table:
    • target type/ref
    • user ID (if present)
    • status
    • outcome code (if present)
    • started/completed/last active timestamps
  • summary cards:
    • total
    • Not started
    • In progress
    • Completed
    • Failed

3.2 UX Rules​

  • show status chips with canonical UI labels, not raw API enums.
  • assignment cohort label mapping:
    • backend invited|started|completed|expired -> UI Not started|In progress|Completed|Expired
  • display timestamps in locale-aware format.
  • make target-linked IDs navigable only when a corresponding glass-box scope link exists; otherwise render plain text.

4. Submission Lens UX​

API source:

  • GET /api/v1/glassbox/submissions/\{id\}
  • optional lang query for localized snapshot projection

Primary purpose:

  • forensic record view for a single submission.

4.1 Layout​

Sections:

  1. Submission header
  2. Snapshot context
  3. Response items
  4. Evidence + ledger timeline
  5. Amendment history
  6. Verification summary
  7. KOE + proof readiness summary

4.2 Required Content​

Header:

  • submission ID
  • evaluation version ID
  • user ID
  • org unit ID
  • attempt number
  • status
  • score/max score/outcome (if present)
  • created/completed timestamps

Snapshot:

  • render versionSnapshot as frozen context
  • if lang is used, show locale projection metadata when returned

Items:

  • item position + question version ID
  • answer payload (read-only rendering)
  • per-item score/correctness/time-spent when available

Ledger/amendments:

  • event list with event type, actor, timestamp
  • amendment history entries (previousEventId, reason, evidence payload where present)

Verification:

  • show requiredLevel, providedLevel, overall status
  • show checks:
    • timeCheck
    • geoCheck
    • stepUpCheck

Rule:

  • if check is not_required, present neutral text (not warning/error).

Readiness:

  • show koeStatus + proofReadiness blocks.
  • apply redaction behavior based on link capability.

4.3 Redaction Rule (Critical)​

For link-principal access:

  • reasons under koeStatus.*.reasons and proofReadiness.*.reasons are hidden by default.
  • reveal reasons only when link claims include canViewReadinessReasons=true.

UI requirement:

  • when redacted, show explicit "reasons hidden for this link scope" helper text.

5. Engagement Lens UX​

API source:

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

Primary purpose:

  • timeline projection for one engagement scope.

5.1 Required Content​

  • chronological timeline entries:
    • source
    • event type
    • occurred at
    • engagement/submission/actor references where provided
    • payload summary

5.2 UX Rules​

  • provide source filters (submission, ledger, etc.) for readability.
  • maintain strict read-only framing.
  • support deep links to corresponding submission lens when submission ID is present and permitted.

6. Programme Lens UX​

API source:

  • GET /api/v1/glassbox/programmes/\{id\}

Primary purpose:

  • compliance passport style view for one enrolment scope.

6.1 Required Content​

  • enrolment ID, programme ID, user ID
  • enrolment status
  • passport badge (valid / expired)
  • lifecycle timestamps (started/completed/certified/expires)
  • requirements table:
    • requirement ID
    • evaluation ID / version ID
    • mandatory flag
    • status
    • submission link (if present)
    • attempt count
    • completion timestamp

6.2 UX Rules​

  • visually separate mandatory vs optional requirements.
  • make requirement and submission references navigable where glass-box scope permits.

7. Shared UI States​

All lens pages must support:

  • loading
  • unauthorized (401)
  • not found/scope mismatch (404)
  • read-only method error for unexpected writes (405)
  • stale/freshness indicator for confidence

Error copy must avoid internal details while remaining actionable.

8. Accessibility & Internationalisation​

MUST:

  • keyboard navigation
  • semantic headings/regions for timelines/tables
  • clear read-only labels for controls that look interactive
  • locale-aware time formatting

Submission lens localization:

  • support lang query where provided by API.
  • show fallback behavior clearly when requested locale is not available.

9. Definition of Done (Glass Box Frontend)​

  • Four lens pages implemented with shared read-only shell.
  • Link principal access errors handled (401, 404, 405) with correct messaging.
  • Submission lens renders snapshot/items/ledger/amendments/verification/readiness blocks.
  • Readiness reason redaction is implemented correctly for default link principals.
  • No mutating controls are present in any glass-box page.
  • Accessibility checks pass for timeline + table-heavy views.
  • Visibility/audit expectations are reflected in UI copy (read-only, externally scoped).

10. Navigation Contract Summary​

Glass Box TaskPatternPrimary CTANotes
View assignment cohortSummary + tableOpen target/submission contextRead-only
Verify one submissionForensic detail pageInspect timeline + readinessRedaction-aware
Review engagement progressTimelineFilter by sourceScope-locked
Validate programme passportStatus + checklistOpen requirement contextScope-locked