Repository docs from .qoder/repowiki

Admin Dashboard

Referenced Files in This Document

• main.tsx
• AdminLayout.tsx
• auth-client.ts
• roles.ts
• http.ts
• moderation.ts
• OverviewPage.tsx
• ReportsPage.tsx
• PostsPage.tsx
• UserPage.tsx
• ReportPost.tsx
• UserTable.tsx
• TimelineChart.tsx
• tabs.tsx
• ReportStore.ts

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document describes the administrative dashboard frontend built with React. It covers the application’s routing, layout, authentication and role-based access control, moderation tools, analytics visualization, and data management interfaces. It also explains administrative workflows for content oversight, user management, and system monitoring, along with the integration points to moderation APIs.

Project Structure

The admin frontend is organized around a React Router-based SPA with a dedicated AdminLayout that enforces admin-only access. Pages are grouped by functional domains (overview, users, reports, colleges, branches, logs, feedback, settings, banned words). Shared UI components, services, and stores support consistent behavior across pages.

graph TB
A["main.tsx<br/>Router setup"] --> B["AdminLayout.tsx<br/>Admin shell + sidebar"]
B --> C["OverviewPage.tsx"]
B --> D["UserPage.tsx"]
B --> E["ReportsPage.tsx"]
B --> F["PostsPage.tsx"]
B --> G["CollegePage.tsx"]
B --> H["BranchPage.tsx"]
B --> I["LogPage.tsx"]
B --> J["FeedbackPage.tsx"]
B --> K["BannedWordsPage.tsx"]
L["auth-client.ts<br/>Better Auth client"] --> B
M["roles.ts<br/>Admin role check"] --> B
N["http.ts<br/>Axios clients + interceptors"] --> C
N --> D
N --> E
N --> F
O["moderation.ts<br/>Moderation API"] --> E
O --> F
P["ReportPost.tsx<br/>Report actions"] --> E
Q["UserTable.tsx<br/>User actions"] --> D
R["TimelineChart.tsx<br/>Analytics chart"] --> C
S["tabs.tsx<br/>Sidebar navigation"] --> B
T["ReportStore.ts<br/>Local report state"] --> E

Diagram sources

• main.tsx
• AdminLayout.tsx
• auth-client.ts
• roles.ts
• http.ts
• moderation.ts
• OverviewPage.tsx
• UserPage.tsx
• ReportsPage.tsx
• PostsPage.tsx
• ReportPost.tsx
• UserTable.tsx
• TimelineChart.tsx
• tabs.tsx
• ReportStore.ts

Section sources

• main.tsx
• AdminLayout.tsx
• tabs.tsx

Core Components

• Authentication and session management via Better Auth client configured for admin endpoints.
• Role-based access control enforcing admin/superadmin permissions.
• Centralized HTTP client with credential support and automatic token refresh on 401.
• Store for managing report state locally to reflect UI updates without full reloads.
• Reusable UI components for tables, dialogs, badges, and charts.

Key responsibilities:

• AdminLayout validates session and role, renders sidebar, and provides outlet for child pages.
• http.ts exposes two clients: adminApiBase for admin endpoints and rootApiBase for non-admin endpoints.
• ReportStore maintains and updates report lists and statuses for optimistic UI.

Section sources

• auth-client.ts
• roles.ts
• http.ts
• ReportStore.ts

Architecture Overview

The admin app uses a nested routing model under AdminLayout. Navigation is driven by a constant tab list. Authentication is enforced at the layout level, redirecting unauthorized users to sign-in and restricting access to admin-only roles. HTTP requests leverage interceptors for token injection and automatic refresh.

sequenceDiagram
participant Browser as "Browser"
participant Router as "React Router"
participant Layout as "AdminLayout"
participant Auth as "auth-client"
participant Roles as "roles.ts"
participant Server as "Server"
Browser->>Router : Navigate to "/"
Router->>Layout : Render AdminLayout
Layout->>Auth : getSession()
Auth-->>Layout : Session {user, role}
Layout->>Roles : hasAdminAccess(role)
alt Not admin
Layout->>Auth : signOut()
Layout-->>Browser : Redirect to "/auth/signin"
else Admin
Layout-->>Browser : Render sidebar + outlet
end

Diagram sources

• AdminLayout.tsx
• auth-client.ts
• roles.ts

Detailed Component Analysis

Routing and Page Organization

• Routes define nested pages under AdminLayout and an AuthLayout for sign-in.
• Dynamic routes support viewing posts, comments, and users by ID.
• Wildcard route handles unknown paths gracefully.

flowchart TD
Start(["App start"]) --> RouterInit["CreateBrowserRouter"]
RouterInit --> AdminRoutes["Admin routes under AdminLayout"]
AdminRoutes --> Overview["/ -> OverviewPage"]
AdminRoutes --> Users["/users -> UserPage"]
AdminRoutes --> Reports["/reports -> ReportsPage"]
AdminRoutes --> Posts["/p/:id, /c/:id, /u/:id -> PostsPage"]
AdminRoutes --> Colleges["/colleges -> CollegePage"]
AdminRoutes --> Branches["/branches -> BranchPage"]
AdminRoutes --> Logs["/logs -> LogPage"]
AdminRoutes --> Feedbacks["/feedbacks -> FeedbackPage"]
AdminRoutes --> Settings["/settings -> OverviewPage"]
AdminRoutes --> BannedWords["/banned-words -> BannedWordsPage"]
AdminRoutes --> NotFound["* -> NotFoundPage"]
RouterInit --> AuthRoutes["Auth routes under AuthLayout"]
AuthRoutes --> SignIn["/auth/signin -> SignInPage"]

Diagram sources

• main.tsx

Section sources

• main.tsx

Admin Layout and Sidebar

• Mobile-responsive sidebar with collapsible menu.
• Sidebar items sourced from a constant list of tabs.
• Session validation and role checks occur on mount and navigation changes.
• Uses a toast library for user feedback.

flowchart TD
Init["Mount AdminLayout"] --> LoadSession["authClient.getSession()"]
LoadSession --> CheckRole{"hasAdminAccess(role)?"}
CheckRole --> |No| SignOut["signOut() + navigate('/auth/signin')"]
CheckRole --> |Yes| SetProfile["Persist profile in store"]
SetProfile --> Render["Render sidebar + outlet"]

Diagram sources

• AdminLayout.tsx
• tabs.tsx

Section sources

• AdminLayout.tsx
• tabs.tsx

Authentication and Role-Based Access

• Better Auth client configured with admin plugin and inferred fields.
• Admin access validated against a set of roles.
• On missing or invalid session, redirects to sign-in and clears profile.

sequenceDiagram
participant Layout as "AdminLayout"
participant Auth as "auth-client"
participant Roles as "roles.ts"
Layout->>Auth : getSession()
Auth-->>Layout : {user, role}
Layout->>Roles : hasAdminAccess(role)
alt Unauthorized
Layout->>Auth : signOut()
Layout-->>Browser : Navigate to "/auth/signin"
else Authorized
Layout-->>Layout : Continue rendering
end

Diagram sources

• auth-client.ts
• roles.ts
• AdminLayout.tsx

Section sources

• auth-client.ts
• roles.ts

HTTP Client and Token Refresh

• Two Axios instances: adminApiBase for admin endpoints and rootApiBase for non-admin endpoints.
• Request interceptor injects Authorization header when present.
• Response interceptor normalizes backend envelope to a unified ApiResponse shape.
• Automatic refresh flow on 401 with queued retry for concurrent requests.

flowchart TD
Req["HTTP Request"] --> Inject["Inject Authorization header"]
Inject --> Send["Send to server"]
Send --> Resp{"Response OK?"}
Resp --> |Yes| Normalize["Normalize response envelope"]
Normalize --> Done["Return ApiResponse"]
Resp --> |No & 401| Refresh["POST /auth/refresh"]
Refresh --> NewToken{"New access token?"}
NewToken --> |Yes| Retry["Retry original request with new token"]
Retry --> Done
NewToken --> |No| Queue["Queue concurrent requests"]
Queue --> Done

Diagram sources

• http.ts

Section sources

• http.ts

Analytics and Overview

• Overview page fetches dashboard metrics and displays counts for users, posts, and comments.
• TimelineChart demonstrates a reusable chart component for time-series-like data.

sequenceDiagram
participant Page as "OverviewPage"
participant HTTP as "http.ts"
participant Server as "Server"
Page->>HTTP : GET /dashboard/overview
HTTP->>Server : Request
Server-->>HTTP : {users, posts, comments}
HTTP-->>Page : ApiResponse
Page-->>Page : Render cards

Diagram sources

• OverviewPage.tsx
• http.ts

Section sources

• OverviewPage.tsx
• TimelineChart.tsx

Moderation Tools and Reporting

• ReportsPage lists reported posts with filtering by status (pending, resolved, ignored) and pagination.
• PostsPage aggregates recent reports for quick moderation.
• ReportPost component provides a table of reports with contextual actions (ban/unban, shadow ban, suspend, ignore, undo).
• ReportStore optimistically updates report status to improve responsiveness.

sequenceDiagram
participant Page as "ReportsPage"
participant HTTP as "http.ts"
participant Store as "ReportStore"
participant Comp as "ReportPost"
participant Server as "Server"
Page->>HTTP : GET /manage/reports?page&limit&status
HTTP->>Server : Request
Server-->>HTTP : {data, pagination}
HTTP-->>Page : ApiResponse
Page->>Store : setReports(data)
Page->>Comp : Render reports
Comp->>HTTP : PUT /moderation/posts/ : id/moderation-state
Comp->>HTTP : PATCH /reports/ : id
HTTP->>Server : Apply moderation
Server-->>HTTP : OK
HTTP-->>Comp : ApiResponse
Comp->>Store : updateReportStatus(...)
Comp-->>Page : onRefresh()

Diagram sources

• ReportsPage.tsx
• PostsPage.tsx
• ReportPost.tsx
• ReportStore.ts

Section sources

• ReportsPage.tsx
• PostsPage.tsx
• ReportPost.tsx
• ReportStore.ts

User Management

• UserPage lists users with search by username/email and pagination.
• UserTable provides actions to ban/unban, suspend/remove suspension, and view user profiles.
• Suspensions are temporary and tracked with end dates.

sequenceDiagram
participant Page as "UserPage"
participant HTTP as "http.ts"
participant Table as "UserTable"
participant Server as "Server"
Page->>HTTP : GET /users?limit&offset
HTTP->>Server : Request
Server-->>HTTP : {users, total}
HTTP-->>Page : ApiResponse
Page->>Table : Render users
Table->>HTTP : PUT /users/ : id/moderation-state {blocked,suspension}
HTTP->>Server : Apply moderation
Server-->>HTTP : OK
HTTP-->>Table : ApiResponse
Table-->>Page : Update local state

Diagram sources

• UserPage.tsx
• UserTable.tsx

Section sources

• UserPage.tsx
• UserTable.tsx

Banned Words Management

• moderation.ts defines typed APIs for banned word configuration, listing, creation, updates, and deletion.
• BannedWordsPage would integrate these APIs to manage word lists and severities.

classDiagram
class ModerationAPI {
+getConfig() ApiResponse
+listWords() ApiResponse
+createWord(payload) ApiResponse
+updateWord(id, payload) ApiResponse
+deleteWord(id) ApiResponse
}

Diagram sources

• moderation.ts

Section sources

• moderation.ts

Dependency Analysis

• AdminLayout depends on auth-client and roles for session validation and role checks.
• Pages depend on http.ts for API communication and on shared components for UI.
• ReportPost and UserTable encapsulate moderation actions and rely on ReportStore for optimistic updates.
• http.ts centralizes interceptors and token refresh logic, reducing duplication across modules.

graph LR
AdminLayout["AdminLayout.tsx"] --> AuthClient["auth-client.ts"]
AdminLayout --> Roles["roles.ts"]
OverviewPage["OverviewPage.tsx"] --> Http["http.ts"]
ReportsPage["ReportsPage.tsx"] --> Http
PostsPage["PostsPage.tsx"] --> Http
UserPage["UserPage.tsx"] --> Http
ReportPost["ReportPost.tsx"] --> Http
UserTable["UserTable.tsx"] --> Http
ReportPost --> ReportStore["ReportStore.ts"]
ReportsPage --> ReportStore
ModerationAPI["moderation.ts"] --> ReportPost
ModerationAPI --> PostsPage

Diagram sources

• AdminLayout.tsx
• auth-client.ts
• roles.ts
• http.ts
• OverviewPage.tsx
• ReportsPage.tsx
• PostsPage.tsx
• UserPage.tsx
• ReportPost.tsx
• UserTable.tsx
• ReportStore.ts
• moderation.ts

Section sources

• AdminLayout.tsx
• http.ts

Performance Considerations

• Local state updates via ReportStore avoid unnecessary network round-trips for UI responsiveness.
• Pagination on user and report listings reduces initial payload sizes.
• Conditional rendering and memoization patterns (e.g., status filters) minimize re-renders.
• Chart components are responsive and should be used judiciously to avoid heavy computations on large datasets.

Troubleshooting Guide

Common issues and resolutions:

• Unauthorized access: Ensure the session has admin/superadmin role; otherwise, the layout will sign out and redirect to sign-in.
• 401 responses: The HTTP client automatically attempts token refresh; if refresh fails, requests are rejected and the app navigates to sign-in.
• Report actions failing: Verify that the action is permitted given current states (e.g., shadow ban is not allowed for comments); check toast messages for specific errors.
• User suspension: Confirm suspension days are positive integers and reason is non-empty before submitting.

Operational checks:

• Confirm VITE_SERVER_URI is set so the auth client targets the correct base URL.
• Validate that the backend endpoints for moderation and management are reachable.

Section sources

• AdminLayout.tsx
• http.ts
• ReportPost.tsx
• UserTable.tsx

Conclusion

The admin dashboard frontend provides a robust, role-protected interface for content oversight, user management, and system monitoring. Its modular structure, centralized HTTP client, and optimistic UI updates enable efficient moderation workflows. The integration with Better Auth ensures secure and seamless admin sessions, while reusable components promote consistency and maintainability.