# Admin Role & UI Implementation Plan

Context: extend MotoVaultPro with an administrative user model, cross-tenant CRUD authority, and surfaced controls within the existing settings experience. Follow phases in order; each phase is shippable and assumes Docker-based validation per `CLAUDE.md`.

## Phase 1 – Access Control Foundations
- Create `backend/src/features/admin/` capsule scaffolding (api/, domain/, data/, migrations/, tests/).
- Add migration `001_create_admin_users.sql` for table `admin_users (auth0_sub PK, email, created_at, created_by, revoked_at)`.
- Seed first record (`admin@motorvaultpro.com`, `created_by = system`) via migration or bootstrap script.
- Extend auth plugin flow to hydrate `request.userContext` containing `userId`, `email`, `isAdmin`, `adminRecord`.
- Add reusable guard `authorizeAdmin` in `backend/src/core/middleware/admin-guard.ts`; return 403 with `{ error: 'Forbidden', message: 'Admin access required' }`.
- Unit tests: guard behavior, context resolver, seed idempotency.

## Phase 2 – Admin Management APIs
- Implement `/api/admin/admins` controller with list/add/revoke/reinstate endpoints; enforce “at least one active admin” rule in repository.
- Add audit logging via existing `logger` (log `actorAdminId`, `targetAdminId`, `action`, `context`).
- Provide read-only `/api/admin/users` for user summaries (reusing existing repositories, no data mutation yet).
- Integration tests validating: guard rejects non-admins, add admin, revoke admin while preventing last admin removal.

## Phase 3 – Platform Catalog CRUD
- Add service `vehicleCatalog.service.ts` under admin feature to manage `vehicles.make|model|model_year|trim|engine|trim_engine`.
- Expose `/api/admin/catalog/...` endpoints for hierarchical CRUD; wrap mutations in transactions with referential validation.
- On write, call new cache helper in `backend/src/features/platform/domain/platform-cache.service.ts` to invalidate keys `platform:*`.
- Record admin change history in table `platform_change_log` (migration `002_create_platform_change_log.sql`).
- Tests: unit (service + cache invalidation), integration (create/update/delete + redis key flush assertions).

## Phase 4 – Station Oversight
- Implement `/api/admin/stations` for global station CRUD and `/api/admin/users/:userId/stations` to manage saved stations.
- Ensure mutations update `stations` and `saved_stations` tables with soft delete semantics and invalidation of `stations:saved:{userId}` plus cached search keys.
- Provide optional `force=true` query to hard delete (document usage, default soft delete).
- Tests covering cache busting, permission enforcement, and happy-path CRUD.

## Phase 5 – UI Integration (Settings-Based)
- Create hook `frontend/src/core/auth/useAdminAccess.ts` that calls `/auth/verify`, caches `isAdmin`, handles loading/error states.
- Desktop: update `frontend/src/pages/SettingsPage.tsx` to inject an “Admin Console” card when `isAdmin` true (links to admin subroutes) and display access CTA otherwise.
- Mobile: add admin section to `frontend/src/features/settings/mobile/MobileSettingsScreen.tsx` using existing `GlassCard` pattern; hide entirely for non-admins.
- Route stubs (e.g. `/garage/settings/admin/*`) should lazy-load forthcoming admin dashboards; guard them with `useAdminAccess`.
- Frontend tests (Jest/RTL) verifying conditional rendering on admin vs non-admin contexts.

## Phase 6 – Quality Gates & Documentation
- Run backend/ frontend lint + tests inside containers (`make rebuild`, `make logs`, `make test-backend`, `docker compose exec mvp-frontend npm test`).
- Author `docs/ADMIN.md` summarizing role management workflow, API catalog, cache rules, and operational safeguards.
- Update existing docs (`docs/PLATFORM-SERVICES.md`, `docs/VEHICLES-API.md`, `docs/GAS-STATIONS.md`, `docs/README.md`) with admin references.
- Prepare release checklist: database migration order, seed verification for initial admin, smoke tests on both device classes (mobile + desktop), rollback notes.
- Confirm Traefik `/auth/verify` headers expose admin flag where needed for downstream services.