Admin Panel & User Management
Relevant source files
The following files were used as context for generating this wiki page:The Admin Panel is a privileged section of the web application designed for system administrators. It provides a centralized interface for monitoring system-wide statistics, managing user accounts, and reviewing audit logs of important system events. Access is restricted to users with the ADMIN role.
The panel is a single-page application built with React, which communicates with a dedicated set of RESTful API endpoints. These endpoints provide aggregated data and administrative actions, ensuring a clear separation of concerns between the frontend presentation and backend business logic.
Architecture Overview
The Admin Panel consists of a main React component, Admin.tsx, which acts as a container and router for different sub-panels: Dashboard, Users, and Logs. Each sub-panel fetches data from corresponding API routes defined in admin.ts. All admin routes are protected by the requireAdmin pre-handler, which verifies the user's JWT and role.
This diagram illustrates the high-level interaction between the frontend components and the backend API.
Admin Dashboard
The dashboard provides a real-time snapshot of the platform's health and usage. It is the default view of the Admin Panel.
Key Statistics
The dashboard displays two types of statistics: aggregate counts and time-series data.
-
Aggregate Stats: A collection of key metrics across the entire system.
- Total Users
- Total Domains (and count of verified ones)
- Total Inboxes
- Total Messages
- Total Rules
- Open Abuse Reports
Sources: services/api/src/routes/admin.ts:8-29, services/web/src/components/admin/AdminDashboard.tsx
-
Time-Series Stats: Daily counts for the last 7 days, used to render charts for:
- New Emails
- New Users
- New Inboxes
Sources: services/api/src/routes/admin.ts:32-94, services/web/src/components/admin/AdminDashboard.tsx
Data Flow
The following diagram shows the sequence of fetching and displaying dashboard statistics.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/stats | Fetches aggregate statistics for the entire platform. |
GET | /admin/stats/timeseries | Fetches daily counts of new users, emails, and inboxes for the last 7 days. |
GET | /admin/system-info | Retrieves general system information like user counts and server time. |
Sources: services/api/src/routes/admin.ts:8-30, services/api/src/routes/admin.ts:32-94, services/api/src/routes/admin.ts:434-455
User Management
This section allows administrators to view, search, and manage all user accounts on the platform.
Sources: services/web/src/components/admin/AdminUsers.tsx, services/api/src/routes/admin.ts:97-248
Features
- List Users: Displays a paginated list of all users with their email, role, verification status, and creation date.
- Search & Filter: Users can be searched by email and filtered by role (
USERorADMIN). - Update User: Admins can change a user's role or disable their account. An admin cannot disable their own account.
- Delete User: Permanently deletes a user and all their associated data (domains, inboxes, messages) in a single database transaction. An admin cannot delete their own account.
- Force Verify: Manually marks a user's email as verified.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/users | Lists users with pagination, search, and filtering. |
PATCH | /admin/users/:id | Updates a user's role or isDisabled status. |
DELETE | /admin/users/:id | Deletes a user and all their associated data. |
POST | /admin/users/:id/verify | Force-verifies a user's email address. |
Sources: services/api/src/routes/admin.ts:97-248
GET /admin/users Parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
search | string | Yes | Search query for user email (case-insensitive). |
role | UserRole | Yes | Filter by user role (USER or ADMIN). |
limit | number | Yes | Number of users to return (default 20, max 100). |
offset | number | Yes | Number of users to skip for pagination. |
Sources: services/api/src/routes/admin.ts:99-106
User Deletion Flow
The user deletion process is critical as it performs a cascading delete of all user-owned resources. This is handled within a database transaction to ensure atomicity.
The diagram below illustrates the sequence of events when an admin deletes a user.
Audit Logging
The Admin Panel includes a comprehensive audit logging system to track significant actions performed by users and administrators.
Sources: services/web/src/components/admin/AdminLogs.tsx, services/api/src/routes/admin.ts:251-378
Features
- View Logs: Displays a paginated, time-stamped list of all audit log entries.
- Filter Logs: Logs can be filtered by action type (e.g.,
LOGIN,DOMAIN_CREATED) and date range. - Export to CSV: Administrators can export the filtered audit logs to a CSV file for offline analysis or archiving.
Logged Actions
The system records various actions, including but not limited to:
USER_REGISTEREDLOGINDOMAIN_CREATEDDOMAIN_VERIFIEDDOMAIN_DELETEDINBOX_CREATEDMESSAGE_DELETEDUSER_UPDATEDUSER_DELETED
Sources: services/web/src/components/admin/AdminLogs.tsx:81-108
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/audit-logs | Lists audit logs with pagination and filtering. |
GET | /admin/audit-logs/export | Exports audit logs to a CSV file. |
Sources: services/api/src/routes/admin.ts:251-378
GET /admin/audit-logs Parameters
| Parameter | Type | Optional | Description |
|---|---|---|---|
action | string | Yes | Filter by a specific action type. |
userId | string | Yes | Filter logs for a specific user ID. |
limit | number | Yes | Number of logs to return (default 50, max 100). |
offset | number | Yes | Number of logs to skip for pagination. |
Sources: services/api/src/routes/admin.ts:253-260
Initial Admin Creation
An administrative user is required to access the Admin Panel. A default admin user is seeded on the first boot of the application when using Docker Compose. The credentials are set by DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD environment variables.
Sources: README.md:32-35