[feature]: Frontend Admin Management Dashboard

[CodeLittleToImprove]

Parsed project fields

[Importance:] Main
[Duration:] 3 Days
{P1}

Intended area

Frontend

Problem / goal

Create a Admin Panel within the existing (site) layout to manage user states. The admin should be able to search a user by Email/Username/UUID, edit stats and be able to deactivate a user. This ticket focuses on the Admin's ability to view and edit user data; it relies on the data structures provided by the Stats, Friend, and Clan services via the BFF.

Scope

Frontend Pages/Components:
apps/frontend/app/(site)/admin/page.tsx (New) (Main Dashboard)
src/components/admin/UserTable.tsx (New) (Needs to use Pagination)
src/components/admin/UserSearchForm.tsx (New) (Debounced Email/User/UUID search)
src/components/admin/AdminUserProfile.tsx (New) (Detailed User View Modal)
apps/frontend/app/(site)/userprofile/page.tsx (Update) (Dynamic Profile update (not directly part of this ticket)
src/components/admin/UserStatsEditor.tsx (New) (Validation-ready stat editing)
src/components/admin/ActionConfirmDialog.tsx (Confirmation wrapper)

Hooks
useStats.ts new(Extended with Mutation logic)
useAdminActions.ts new (Disable/Enable/Revoke/Search)
useAdminNotifications.ts new (Toast/Feedback system)

Backend (BFF)
apps/BFF/src/modules/auth/auth.controller.ts (Proxy Admin actions)
apps/BFF/src/modules/social/social.controller.ts (Proxy Clan/Friends)

Acceptance criteria

1. Admin Management Dashboard

• Access Control: The /admin route must check the user.role from useAuth(). Non-admins should be redirected or shown an "Unauthorized" state.
• Search: Support for Username, UUID, and Email. Must include debouncing to prevent API spam and pagination for results > 20.
• Role & Status: Admins can toggle "Disabled" status and change roles (User/Mod/Admin).
• Force Logout: Revoke active sessions via the backend; UI must update to reflect the "Kicked" state.
• User Modal: Clicking a user in the table opens a detailed view showing their Clan membership, Friend list, and full Match History.
• Frontend Cleanup: The Providers.tsx logic must catch the 401 error or "unauthorized" event to clear sessionStorage and redirect the user, when a user without the admin role tries to access the Admin Management Dashboard.

2. Social & Clan Integration

• Clan Data: Display the user's current Clan name, tag, and member count on the profile.
• Friend List: Show a list of friends with real-time status indicators (Online/Offline).
• Stats Dashboard: Display performance metrics (Win/Loss, Rank) fetched from the Stats service.

3. Stats Management

• Admin Control: Admins can manually override Win/Loss records and other stats
• Validation: Negative numbers or nonsensical values (e.g., more wins than total games) must be rejected by the UI and API.
• Mutation Hooks: Use the updated useStats hook to handle the PATCH requests back to the Stats microservice via the BFF.

4. Safety & Feedback

• Confirmation: Destructive actions (Disable, Force Logout, Stat Wipe) must trigger a confirmation dialog.
• Toasts: Success/Error notifications for every admin action via useAdminNotifications.
• Loading States: Skeletons for search results and "pending" states for action buttons.

5. Shared Hook & Hand-off

• Universal Hook: The useStats hook must be architected to be "Plug-and-Play" so it can be used by both the Admin Modal (this ticket) and the dynamic Profile Page (Ticket [feature]: Frontend: make user-profile page use dynamic routing and data fetching #143).
• Admin-Only Mutations: Ensure the PATCH capabilities of the hook are properly protected and only used within the Admin context.

Technical notes

• BFF Proxying: The BFF must act as the single entry point. It needs to "proxy" requests from the frontend to the auth-user, stats, and social microservices.
• Error Boundaries: Wrap the Admin Dashboard in a React Error Boundary to prevent a single failed fetch from crashing the entire panel.
• Zod Validation: Use Zod for the Stats Editor form to ensure strict type safety on the frontend.

Test plan

CRUD Operations:

• Search for a test user.

• Change their role to ADMIN

• Refresh and verify the UserTable displays the updated role.

• Permission Check: Log in with a standard USER role account and attempt to navigate to /admin. Verify the page is blocked.

• BFF Flow: Verify that a single call to the BFF correctly aggregates or forwards data to the internal stats and social services.

• Clan Display: Verify the profile page correctly renders a "No Clan" state vs an "Active Clan" state.

Profile Verification:

• Navigate to /userprofile.
• Verify that stats match the data returned by the Stats service via the BFF.

Search Verification:

• Search by partial email and verify the debounced request only fires once.

Destructive Action Flow:

• Trigger "Force Logout," cancel the confirmation dialog (verify no action), then re-trigger and confirm

Stats validation

• change a stat of a user in the userstats editor to a nonsense value and it should be rejected and not updated

Checklist

• I checked whether this depends on another service, API contract, or database change.
• I added enough detail so another teammate can implement this without guessing.
• I included validation and test expectations.

[onlyHydra]

🚀 Branch created from development: 142_codelittletoimprove

To check out this branch locally:

git fetch --prune && git checkout 142_codelittletoimprove

[onlyHydra]

User Profile View Modal/Page (Admin Context)
File:apps/frontend/src/components/admin/AdminUserProfile.tsx(New)
Display selected user's full profile with stats, clan, friends within admin dashboard

Search Form with Email Support
File:apps/frontend/src/components/admin/UserSearchForm.tsx(New)
Search criteria: UsernameAND Email(ticket only mentions Username/UUID)
Add debouncing + pagination for results

Stats Editor Component
File:apps/frontend/src/components/admin/UserStatsEditor.tsx(New)
Allow editing user stats (Win/Loss, Rank, etc.)
Validation for stat changes
Missing from ticket entirely- you need this

Action Confirmation Dialogs
File:apps/frontend/src/components/admin/ActionConfirmDialog.tsx(New)
Confirm before disable/enable account
Confirm before force logout
Confirm before updating stats

Notification/Toast System
File:apps/frontend/src/hooks/useAdminNotifications.ts(New)
Success/error feedback for admin actions
Real-time status updates

Error & Loading States
Add error boundaries for admin dashboard
Loading skeletons for user search results
Error states for failed stat updates

Update useStats Hook
Currently scoped for "display metrics"
Extend to:useStats.ts- add mutation hooks for updating stats
Add useUserSearch hook for querying users by email/username
Add useAdminActions hook (disable/enable/revoke sessions)

Updated Acceptance Criteria to Add:

Search:Find users by Username, Email,OR UUID(ticket only has Username/UUID)
Stats Editing:Admin can modify user Win/Loss/Rank stats from dashboard
Action Feedback:Toast notifications for all admin actions (disable, role change, logout, stat updates)
Confirmation:Destructive actions require confirmation dialog
Stat Validation:Invalid stat changes are rejected with error message
Search Pagination:Results paginated if >20 users found
New Dependencies to Consider:

Toast/notification library (if not exists)
Form validation library for stats editor
Confirmation dialog component