Admin: Order Management

Relevant source files

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

• app/admin/orders/page.tsx
• features/orders/hooks/use-orders-admin.ts
• features/orders/components/orders-list-table.tsx
• features/orders/components/order-status-update-dialog.tsx
• app/admin/orders/[id]/page.tsx
• features/orders/services/orders.service.ts
• types/order.types.ts
• features/orders/components/orders-table-columns.tsx

The Admin Order Management module provides administrators with the tools to view, search, filter, and update customer orders. It is a core part of the admin panel, enabling staff to track the entire lifecycle of an order from placement to delivery or cancellation.

This system is built using Next.js and React, leveraging @tanstack/react-query for server state management and a feature-based architecture. The UI is composed of several key components that handle displaying lists of orders, viewing individual order details, and modifying order statuses through interactive dialogs.

Architecture Overview

The Order Management feature follows a standard client-side data fetching pattern. UI components trigger data requests and mutations via custom React Query hooks. These hooks abstract the logic of calling a dedicated OrdersService, which in turn communicates with the backend API.

This diagram illustrates the high-level interaction between the main components of the feature.

Key Components

The user interface is divided into several reusable React components, each with a specific responsibility.

Component	File Path	Description
AdminOrdersPage	app/admin/orders/page.tsx	The main page component. Manages state for filters (query), orchestrates data fetching, and handles user interactions like pagination and opening the status update dialog.
OrdersListTable	features/orders/components/orders-list-table.tsx	Displays a paginated and sortable list of orders using @tanstack/react-table. It receives callbacks for viewing details and updating status.
createOrdersTableColumns	features/orders/components/orders-table-columns.tsx	A function that defines the column structure for the OrdersListTable, including headers, cell rendering, and action dropdowns.
OrderDetailPage	app/admin/orders/[id]/page.tsx	A page dedicated to showing the full details of a single order. It fetches the order data using its ID from the URL.
OrderDetailView	features/orders/components/order-detail-view.tsx	A presentational component that renders the detailed information of an order, including items, totals, and status badges.
OrderStatusUpdateDialog	features/orders/components/order-status-update-dialog.tsx	A modal dialog that allows an admin to change the status and paymentStatus of a selected order.

Sources: app/admin/orders/page.tsx, features/orders/components/orders-list-table.tsx, features/orders/components/orders-table-columns.tsx, app/admin/orders/[id]/page.tsx, features/orders/components/order-detail-view.tsx, features/orders/components/order-status-update-dialog.tsx

Data Management

Data fetching and state mutations are handled by a combination of React Query hooks and a dedicated service class.

React Query Hooks

Custom hooks provide a clean API for components to interact with server data, handling caching, invalidation, and loading/error states automatically.

• useOrdersAdminList(query): Fetches a paginated list of orders based on the provided filter query. It uses the query object as part of its queryKey to ensure data is re-fetched when filters change.

  • Query Key: [...queryKeys.products.lists(), "admin", params]
  • Function: ordersApi.listAllOrders(query)
    Sources: features/orders/hooks/use-orders-admin.ts:16-23

• useUpdateOrderStatus(): Provides a mutation function to update an order's status. On success, it invalidates the queries for both the order list and the specific order's detail view to ensure the UI reflects the change. It also displays toast notifications for success or error.

  • Mutation Function: ordersApi.updateStatus(orderId, data)
  • On Success: Invalidates queryKeys.orders.lists() and queryKeys.orders.detail(orderId).
    Sources: features/orders/hooks/use-orders-admin.ts:40-59

Service Layer: OrdersService

The OrdersService class encapsulates all API communication related to orders. For admin management, it provides the following key methods:

• listAllOrders(query): Constructs a URLSearchParams object from the OrderAdminListQuery and makes a GET request to /orders/admin/all.
• getById(orderId): Fetches a single order by its ID via a GET request to /orders/{orderId}.
• updateStatus(orderId, data): Sends a PATCH request to /orders/{orderId}/status with the new status data.

Sources: features/orders/services/orders.service.ts:103-113, features/orders/services/orders.service.ts:74-79, features/orders/services/orders.service.ts:85-93

API Endpoints

The frontend service interacts with the following backend API endpoints for order management:

Method	Endpoint	Description
GET	/orders/admin/all	Retrieves a paginated list of all orders.
GET	/orders/:orderId	Retrieves the details of a single order.
PATCH	/orders/:orderId/status	Updates the status and/or payment status of an order.

Sources: features/orders/services/orders.service.ts

Data Models

The core data structures for order management are defined in types/order.types.ts.

Entity Relationship

This diagram shows the relationship between an Order and its OrderItems.

OrderAdminListQuery Interface

This interface defines the available filters for querying the admin order list.

Field	Type	Description
page	number?	The page number for pagination.
pageSize	number?	The number of items per page.
status	OrderStatus?	Filter by order status.
paymentStatus	PaymentStatus?	Filter by payment status.
search	string?	Search by order ID or user ID/email.
startDate	string?	ISO date string for the start of a date range.
endDate	string?	ISO date string for the end of a date range.

Sources: types/order.types.ts:131-140

Enums

OrderStatus

• PENDING
• PROCESSING
• SHIPPED
• DELIVERED
• CANCELLED
  Sources: types/order.types.ts:10-16

PaymentStatus

• UNPAID
• PAID
  Sources: types/order.types.ts:18-21

User Interaction Flows

Viewing the Order List

This sequence diagram shows the flow of data when an admin navigates to the order list page.

Updating an Order's Status

This diagram shows the process of an admin updating an order's status.