Admin: User Management

Relevant source files

The following files were used as context for generating this wiki page:

• app/admin/users/page.tsx
• features/users/hooks/use-users-list.ts
• features/users/services/users.service.ts
• features/users/components/users-list-table.tsx
• features/users/hooks/use-user-mutations.ts
• types/user.types.ts
• app/admin/users/[id]/page.tsx
• features/users/components/users-table-columns.tsx

The User Management module provides administrators with the tools to view, manage, and modify user accounts within the application. It is a core part of the admin dashboard, accessible via the /admin/users route. This system allows for listing all users with pagination and filtering, viewing detailed user information, updating user details (like role and status), and deactivating accounts.

The architecture follows a feature-based organization, separating UI components, data-fetching logic (hooks), and API communication (services). State management for server data is handled by TanStack Query (@tanstack/react-query), ensuring efficient data fetching, caching, and synchronization with the backend.

Architecture Overview

The User Management feature is composed of several layers: the Page component, which acts as the entry point; UI components for displaying data and handling user input; React Query hooks for managing server state; and a service class that communicates with the backend API.

This diagram illustrates the high-level component architecture for the user list view.

Core Components

The user interface is built from several key React components.

Component	File Path	Description
AdminUsersPage	app/admin/users/page.tsx	The main page component. It orchestrates data fetching, manages state for filters and dialogs, and handles user actions like editing and deactivating.
UsersListTable	features/users/components/users-list-table.tsx	A data table built with @tanstack/react-table to display the list of users. It supports sorting and pagination.
createUsersTableColumns	features/users/components/users-table-columns.tsx	A function that defines the columns for the UsersListTable, including user details and an "actions" menu for viewing, editing, and deactivating.
UserDetailPage	app/admin/users/[id]/page.tsx	A page to display detailed information about a single user. It also provides entry points for editing or deactivating the specific user.
UserEditFormDialog	app/admin/users/page.tsx:21	A dialog component that contains a form for updating a user's information, such as their full name, phone number, role, and active status.
UserDeactivateDialog	app/admin/users/page.tsx:22	A confirmation dialog to prevent accidental deactivation of a user account.

Sources: app/admin/users/page.tsx, features/users/components/users-list-table.tsx, features/users/components/users-table-columns.tsx, app/admin/users/[id]/page.tsx

Data Flow and State Management

Data fetching and mutations are handled by React Query hooks, which call methods on the UsersService.

Fetching User List

The useUsersList hook is responsible for fetching a paginated and filtered list of users from the backend.

This sequence diagram shows the data flow when the AdminUsersPage loads.

User Mutations

Mutations like updating or deactivating a user are handled by useUpdateUser and useDeactivateUser hooks. These hooks manage the asynchronous operation and handle side effects like cache invalidation and displaying toast notifications.

Update User Workflow

This flowchart shows the process of updating a user's details.

Deactivate User Workflow

This flowchart shows the process of deactivating a user.

API Service Layer

All direct communication with the backend API is encapsulated within the UsersService class. This class uses a shared apiClient for making HTTP requests and validates responses against Zod schemas.

Source: features/users/services/users.service.ts

Service Methods

Method	HTTP Verb & Endpoint	Description
listUsers	GET /users	Fetches a paginated list of users with optional filters.
getUserById	GET /users/{userId}	Retrieves a single user by their ID.
updateUser	PUT /users/{userId}	Updates a user's details (Admin only).
deactivateUser	PUT /users/{userId}/deactivate	Deactivates a user's account (Admin only).

Sources: features/users/services/users.service.ts:57-113

Query Parameter Construction

The listUsers method dynamically builds the query string based on the provided parameters.

// features/users/services/users.service.ts:60-75
async listUsers(query?: ListUsersParams): Promise<ListUsersResponse> {
    const searchParams = new URLSearchParams();

    if (query?.page !== undefined) {
      searchParams.set("page", query.page.toString());
    }
    if (query?.pageSize !== undefined) {
      searchParams.set("pageSize", query.pageSize.toString());
    }
    if (query?.search) {
      searchParams.set("search", query.search);
    }
    if (query?.role) {
      searchParams.set("role", query.role);
    }

    const queryString = searchParams.toString();
    const endpoint = queryString ? `/users?${queryString}` : "/users";

    return apiGetValidated<ListUsersResponse>(
      endpoint,
      ListUsersResponseSchema as z.ZodType<ListUsersResponse>,
    );
}

Source: features/users/services/users.service.ts:60-75

Data Structures

The feature relies on several key data structures defined in types/user.types.ts.

ListUsersQuery

This interface defines the available query parameters for filtering the user list.

Field	Type	Description
page	number?	The page number for pagination.
pageSize	number?	The number of users to return per page.
search	string?	A search term to filter users.
role	UserRole?	Filter users by their role (ADMIN or CUSTOMER).

Source: types/user.types.ts:50-55

UpdateUserRequest

This interface defines the payload for updating a user's information. All fields are optional.

Field	Type	Description
fullName	string?	The user's full name.
phone	string?	The user's phone number.
role	UserRole?	The user's role (ADMIN or CUSTOMER).
isActive	boolean?	The active status of the user's account.

Source: types/user.types.ts:33-39

ListUsersResponse

This interface describes the shape of the data returned from the GET /users endpoint.

Field	Type	Description
users	User[]	An array of user objects.
total	number	The total number of users matching the query.
page	number	The current page number.
pageSize	number	The number of items per page.

Source: types/user.types.ts:68-74