motovaultpro/docs/changes/admin-settings-frontend-plan.md

Admin Settings Frontend Implementation Plan

Audience & Scope

• Intended executor: AI agent implementing MotoVaultPro admin settings UI across desktop and mobile.
• Scope: Frontend-only tasks within frontend/, coordinating with existing backend admin APIs. Includes real-time audit log integration and bulk operations across admin users, catalog entities, and station management.

Current State Summary

• Routes exist (frontend/src/pages/admin/*.tsx, frontend/src/features/admin/mobile/*.tsx) but contain placeholder copy.
• Hooks and API clients (frontend/src/features/admin/hooks/*, frontend/src/features/admin/api/admin.api.ts) already wrap CRUD endpoints but lack bulk helpers and streaming.
• Settings pages link into admin routes; useAdminAccess gate is wired.
• No shared admin layout, tables, or selection utilities; no real-time audit consumption; no bulk UI.

Key Requirements

1. Real-time audit logging for admin operations (desktop + mobile).
2. Bulk operations: multi-select + batch mutate/delete/revoke across admin users, catalog hierarchy, stations.
3. Desktop / Mobile parity while respecting CLAUDE.md mobile + desktop mandate and existing design system.

Assumptions:

• Backend will expose streaming endpoint (/api/admin/audit-logs/stream) using SSE. (If absent, coordinate for addition.)
• Backend will provide/extend batch mutation endpoints or accept arrays in current ones.
• No additional design assets; follow existing Material UI / GlassCard patterns.

Implementation Phases

Phase 0 – Prep & Validation

• Confirm backend endpoints:
  • GET /api/admin/audit-logs/stream (SSE) payload schema.
  • Batch endpoints for admins (POST /admin/admins/bulk, PATCH /admin/admins/bulk-revoke, etc.), catalog (/admin/catalog/{entity}/bulk-delete), stations (/admin/stations/bulk-delete).
  • Response format + error contracts.
• Document agreements in docs/ADMIN.md and update API client typings before UI work.

Phase 1 – Shared Infrastructure

• Add shared admin components under frontend/src/features/admin/components/:
  • AdminSectionHeader
  • AdminDataGrid (wrapper around MUI DataGrid or Table) with checkbox selection and toolbar slot.
  • SelectionToolbar + BulkActionDialog.
  • AuditLogPanel (desktop) and AuditLogDrawer (mobile).
  • EmptyState, ErrorState, Skeleton variants.
• Utility hooks/services:
  • useBulkSelection (manages item selection, select all, reset).
  • useAuditLogStream (SSE handling, merge into cache, pause/resume).
  • useAdminRealtimeEffect (common real-time logic for both platforms).
  • Error normalization helper for API responses.
• Update admin.api.ts to include bulk endpoints and streaming subscription helper.
  • Ensure types in admin.types.ts cover new request/response payloads.

Phase 2 – Admin Users Experience

• Desktop (AdminUsersPage.tsx):
  • Replace placeholder with layout:
    • Header (stats summary cards).
    • AdminDataGrid listing admins (columns: email, role, status, created/updated, last activity).
    • Toolbar actions: Invite, Revoke, Reinstate, Delete (single + bulk), export CSV placeholder.
    • Inline filters/search.
    • Audit log side panel fed by useAuditLogStream.
  • Modals/forms:
    • Invite admin (react-hook-form + Zod validation).
    • Confirm dialogs for revoke/reinstate/delete (bulk friendly).
  • State management:
    • Use React Query hooks (useAdmins, new useBulkRevokeAdmins, etc.).
    • Optimistic updates where safe; fallback to refetch on failure.
    • Surface backend constraints (last admin protection) in toasts/dialogs.
• Mobile (AdminUsersMobileScreen.tsx):
  • Card-based list with segmented controls.
  • Multi-select mode triggered by long-press or “Select” button; sticky bottom action bar for bulk operations.
  • Slide-in drawer for audit log stream; allow collapse to preserve screen space.
  • Ensure loading/error/empty states match mobile pattern.

Phase 3 – Vehicle Catalog Management

• Extend API hooks for per-entity bulk operations (useDeleteMakesBulk, etc.) and streaming updates.
• Desktop (AdminCatalogPage.tsx):
  • Two-column layout: left panel shows hierarchical tree (Makes → Models → Years → Trims → Engines). Right panel shows detail grid for selected level.
  • Support multi-select in each grid with bulk delete; confirm cascading impacts (warn when deleting parents).
  • Modals for create/edit per entity using shared form component (with validation & parent context).
  • Audit log panel filtered to catalog-related actions.
  • Show breadcrumbs + context metadata (created/updated timestamps).
• Mobile (AdminCatalogMobileScreen.tsx):
  • Drill-down navigation (list of makes → models → ...).
  • Selection mode toggles for bulk delete at current depth; use bottom sheet to display actions.
  • Provide “Recent Changes” sheet consuming audit stream (filtered).
• Handle cache invalidation across hierarchies (e.g., deleting a make invalidates models/years/trims queries). Consider using queryClient invalidateQueries with partial keys.

Phase 4 – Station Oversight

• Hook updates: add useBulkDeleteStations, useBulkRestoreStations if available, with optional force flag.
• Desktop (AdminStationsPage.tsx):
  • Data grid with columns (name, address, status, last modified, createdBy). Add search bar and filter chips (active, soft-deleted).
  • Bulk selection with delete (soft/hard toggle), restore, export stub.
  • Station detail drawer with metadata and quick actions.
  • Audit log panel focusing on station events; highlight critical operations via toast (e.g., hard deletes).
• Mobile (AdminStationsMobileScreen.tsx):
  • Card list with quick actions (edit, delete, restore). Multi-select mode with sticky action bar.
  • Provide filter tabs (All / Active / Deleted).
  • Integrate audit log bottom sheet.

Phase 5 – Integration & Routing Enhancements

• Introduce route wrapper/components (e.g., AdminUsersRoute) that detect viewport using useMediaQuery and render desktop or mobile variant; ensures shared logic and prevents duplicate routing code.
• Update navigation flows, ensuring mobile bottom navigation can reach admin sections gracefully.
• Document keyboard shortcuts or focus management for accessibility (bulk selection, audit log toggles).

Phase 6 – Testing & QA

• Add unit tests for new hooks (useAuditLogStream, bulk hooks) using Jest + Testing Library. Mock EventSource for streaming tests.
• Component tests:
  • Desktop grids: selection toggles, bulk action dialogs, form validation.
  • Mobile screens: selection mode toggling, action bar behaviors.
  • Audit log panels: streaming update rendering, pause/resume controls.
• Visual regression smoke tests if tooling available; otherwise document manual screenshot checkpoints.
• Manual QA matrix:
  • Desktop ≥1280px and mobile ≤480px.
  • Test flows: invite admin, revoke/reinstate, bulk revoke, catalog cascading delete, station soft/hard delete, audit log live updates.

Deliverables Checklist

• Updated API client + types for batch + streaming.
• Shared admin UI components & utilities.
• Desktop admin pages fully functional with bulk + real-time features.
• Mobile admin screens matching functionality.
• Comprehensive tests covering new flows.
• Documentation updates (API usage, manual QA steps).

Risks & Mitigations

• Streaming availability: If backend stream not ready, fall back to polling with progressive enhancement; keep SSE integration behind feature flag.
• Bulk API inconsistencies: Align payload format with backend; add defensive UI (disable actions until backend confirms support).
• State synchronization: Ensure query invalidation covers dependent entities; consider structured query keys and queryClient.setQueryData for incremental updates.
• Mobile UX complexity: Prototype selection mode early to validate ergonomics; leverage bottom sheets to avoid cramped toolbars.

Follow-up Questions (Resolved)

1. Real-time audit logs required — implement SSE-based stream handling.
2. Bulk operations mandatory — support multi-select + batch actions across admin users, catalog entities, stations.
3. No additional design constraints — rely on existing Material UI and GlassCard paradigms.

Handoff Notes

• Keep code comments concise per developer guidelines; avoid introducing new design systems.
• Validate hooks for Auth0 dependency (ensure disabled when unauthenticated).
• Coordinate with backend team if API gaps found; document interim shims.
• Maintain responsiveness and accessibility; ensure touch targets ≥44px and keyboard operability on desktop grids.