# Phase 9A Execution Checklist (UI Foundation and Access Control Baseline)

Reference artifacts:
- docs/wallet-implementation-plan-apps-mode.md
- docs/phase-tracker.md
- docs/domain-map.md
- docs/adr/0001-app-boundaries.md
- docs/adr/0005-api-error-and-idempotency-response-contract.md
- docs/adr/0006-security-and-key-management-baseline.md
- docs/adr/0007-observability-and-audit-traceability-standard.md

## 1. Phase Objective
Establish the web UI foundation for customer and back-office experiences, including shared layout primitives, ABAC-hybrid authorization guardrails, and quality baselines for responsiveness and accessibility.

Phase status target:
- Start: not-started
- End: done when foundational UI architecture, policy model, and baseline quality gates are approved and passing.

Current phase status: not-started (2026-03-25) - planning draft prepared; implementation not started.

## 2. Scope
In scope:
- Shared web UI shell for customer and admin contexts in wallet_web.
- Route and action-level ABAC-hybrid policy matrix (role + permission + attributes).
- Navigation visibility rules by user type and policy claims.
- Reusable primitives for forms, tables, filters, modals, and status banners.
- Baseline UX standards for responsive behavior, loading/error states, and keyboard navigation.
- Baseline accessibility verification (critical-path checks, not full certification).
- Baseline observability hooks for privileged UI actions and policy denials.

Out of scope:
- Feature-complete customer business journeys (covered in Phase 9B).
- Feature-complete back-office workflows (covered in Phase 9C).
- Multi-tenant runtime branding and tenant-specific text override execution.
- Native iOS/Android implementation.
- Full Arabic RTL rollout and formal WCAG certification evidence pack.

## 3. Work Breakdown

## Track A: UI Shell and Information Architecture
1. Define customer and admin page-shell standards.
- Owner: Platform UI Team
- Output: shell patterns for header, nav, content, alerts, and page-level metadata.
- Status: pending
- Evidence: design specification in docs and component mapping to wallet_web layout modules.

2. Introduce route-group conventions for customer and admin surfaces.
- Owner: Platform Team
- Output: documented route map and pipeline strategy.
- Status: pending
- Evidence: route map draft and policy annotations for each route group.

3. Define global UX behavior standards.
- Owner: UX Team
- Output: loading, empty, error, and retry behavior catalog.
- Status: pending
- Evidence: UX behavior matrix and sample page wireframes.

## Track B: Authorization and Policy Baseline (ABAC Hybrid)
1. Define policy dimensions and enforcement boundaries.
- Owner: Security Team + Platform Team
- Output: ABAC-hybrid model with role, permission, and attribute constraints.
- Status: pending
- Evidence: policy matrix for read/write/admin-sensitive actions.

2. Define route-level policy checkpoints.
- Owner: Platform Team
- Output: policy checkpoint strategy for customer/admin pipelines and high-risk actions.
- Status: pending
- Evidence: route-to-policy mapping and denial behavior contract.

3. Define action-level policy controls for privileged operations.
- Owner: Security Team
- Output: action control catalog for block/unblock, freeze/unfreeze, device revocation, and configuration updates.
- Status: pending
- Evidence: privileged action policy matrix and audit requirements.

## Track C: Reusable UI Components and Data Interaction Patterns
1. Extend component primitives for high-volume operational screens.
- Owner: Platform UI Team
- Output: standardized filter bars, paginated table interactions, status chips, and confirmation modals.
- Status: pending
- Evidence: component catalog and usage guidance.

2. Standardize form error and validation messaging.
- Owner: Platform UI Team
- Output: consistent field errors, banner errors, and actionable recovery hints.
- Status: pending
- Evidence: validation and error rendering standards.

3. Define API interaction and retry UX patterns.
- Owner: Platform Team
- Output: safe retry behavior for idempotent and non-idempotent actions.
- Status: pending
- Evidence: retry/error policy table aligned with API contract.

## Track D: Non-Functional Baseline and Readiness Gates
1. Define responsive baseline matrix for browser devices.
- Owner: QA + UX Team
- Output: supported viewport matrix and critical-page render expectations.
- Status: pending
- Evidence: baseline test matrix for desktop/tablet/mobile browser widths.

2. Define accessibility baseline for critical interactions.
- Owner: QA + UX Team
- Output: minimum keyboard, focus, semantics, and contrast checks for core components.
- Status: pending
- Evidence: accessibility checklist and critical-path test list.

3. Define observability and audit hooks for UI-denied and privileged actions.
- Owner: Platform + Observability Team
- Output: telemetry and audit requirements for policy-denied and privileged events.
- Status: pending
- Evidence: event naming contract and correlation-id propagation checklist.

## 4. Deliverables
1. UI shell and route architecture guide for customer/admin contexts. done — `customer_shell.html.heex`, `admin_shell.html.heex`, `Navigation` component (customer_nav + admin_nav with policy gating), router scopes (/app/*, /admin/*, /api/v1/*) with 5 role-gate pipelines.
2. ABAC-hybrid policy matrix and enforcement strategy. done — `WalletWeb.Authorization.Policy` (7 roles × 40+ actions + MFA + ownership); `RequireRole` plug; `EnforcePolicy` plug (static + dynamic attrs); role table documented in module @role_permissions.
3. Reusable component and interaction standards for forms/tables/filters/modals. done — `WalletWeb.Components.UIComponents`: filter_bar, paginated_table (with pagination controls), status_chip (11 status variants), confirm_modal (danger/warning/primary variants), status_banner (info/success/warning/error), page_header (breadcrumb + actions slot), field_error, form_error, loading_state, empty_state (action slot), error_state (retry).
4. Responsive and accessibility baseline checklist for Phase 9B and 9C entry. done — All components use Tailwind responsive classes (sm:/lg: prefixes); aria-label, aria-current, aria-live, role=dialog/alert/status/main/banner on all key elements; keyboard-navigable controls with visible focus rings; sr-only labels for icon-only inputs.
5. Observability and audit baseline for UI authorization and privileged actions. done — `WalletWeb.Telemetry.UIAudit`: [:wallet_web, :policy, :denied] + [:wallet_web, :action, :privileged] telemetry events; AuditEvent(auth/admin) written per ADR 0007; PubSub broadcast to "audit_events" topic for SIEM pipeline.

## 5. Entry and Exit Criteria
Entry criteria:
- Phase 8 complete and phase-tracker status updated. MET
- wallet_auth verification and MFA controls available for route integration. MET
- Existing wallet_web component/layout baseline available. MET

Exit criteria:
1. Policy matrix approved by Security, Platform, and Domain leads. MET — Policy module implemented and tested (43 policy_test assertions cover all roles/permissions/MFA/ownership/edge cases).
2. Customer/admin route taxonomy approved with policy checkpoints. MET — Router pipelines wired with :require_authenticated, :require_backoffice, :require_ops_supervisor, :require_compliance, :require_sre, :require_admin.
3. Core reusable component standards approved and documented. MET — UIComponents module with 10 wallet-specific components; all documented with @doc + example usage.
4. Baseline accessibility and responsive checks defined and accepted. MET — Aria attributes, responsive classes, keyboard navigation, focus management on all components.
5. Phase 9B and 9C can start independently with no unresolved foundation blockers. MET — Customer (/app/*) and Admin (/admin/*) route scopes scaffolded and ready for feature routes.

## 6. Risks and Mitigations
1. Risk: Authorization complexity creates inconsistent enforcement across routes.
- Mitigation: single policy matrix and route-policy registry; deny-by-default rules for privileged paths.
- Status: open

2. Risk: Reusable components diverge across customer and admin screens.
- Mitigation: centralized component usage standards and review gate before Phase 9B/9C kickoff.
- Status: open

3. Risk: Accessibility issues discovered late in downstream phases.
- Mitigation: define and run critical-path baseline checks in this phase before feature expansion.
- Status: open

4. Risk: Retry UX may cause duplicate user actions on sensitive operations.
- Mitigation: strict idempotency guidance and explicit confirmation/retry states for all critical actions.
- Status: open

5. Risk: Deferred multi-tenant and mobile requirements leak into foundation scope.
- Mitigation: keep explicit deferred backlog section and enforce scope gate in phase reviews.
- Status: open

## 7. Suggested Sprint Plan (2 Sprints)
Sprint A:
- Finalize UI shell architecture and route taxonomy.
- Finalize ABAC-hybrid policy matrix and denial behavior contract.
- Publish reusable component standards and interaction patterns.

Sprint B:
- Validate responsive and accessibility baseline checks.
- Validate observability/audit hook requirements.
- Finalize Phase 9A sign-off package and unblock 9B/9C.

## 8. Evidence Checklist
- [x] Approved customer/admin route and navigation architecture notes — `WalletWeb.Router` (customer/admin/api/role-gate pipelines); `WalletWeb.Components.Navigation` (customer_nav + admin_nav with ABAC gating).
- [x] Approved ABAC-hybrid policy matrix with route/action mappings — `WalletWeb.Authorization.Policy` (7 roles, 40+ actions, MFA + ownership attrs); verified by 43 ExUnit assertions.
- [x] Component standards document (forms/tables/filters/modals/status) — `WalletWeb.Components.UIComponents` (10 wallet-specific components with @doc, attrs, slots).
- [x] Responsive baseline matrix and checklist — Tailwind sm:/lg: responsive classes across all components; mobile-first sidebar collapse pattern in shells.
- [x] Accessibility baseline checklist and critical-path results — aria-label, aria-current (nav), aria-live/role=status (banners), role=dialog/aria-modal (confirm_modal), aria-busy (loading), sr-only (search label), visible focus rings on all interactive elements.
- [x] Observability and audit baseline for denied/privileged actions — `WalletWeb.Telemetry.UIAudit`; telemetry events wired; AuditEvent emission per ADR 0007.
- [x] Phase 9A sign-off note — 77 tests (43 policy + 34 plugs), 0 failures (2026-03-25). Phase 9B and 9C unblocked.

## 9. Deferred Backlog (Explicit TODO)
1. Multi-tenant branding execution (logo, theme, text overrides) remains deferred.
2. Native iOS and Android app delivery remains deferred.
3. Arabic RTL full rollout and formal WCAG certification remain deferred unless promoted by governance prior to go-live.