ReadMeABook/documentation/admin-dashboard.md

Admin Dashboard

Status: ✅ Implemented

Comprehensive overview of system metrics, active requests, download monitoring, and quick access to settings.

Sections

• Metrics: Total requests, active downloads, completed/failed requests, total users, system health
• Requests Awaiting Approval: Grid of requests pending admin approval (approve/deny buttons, auto-refresh)
• Active Downloads: Real-time table with title, progress, speed, ETA
• Request Management: Full-featured table with filtering, sorting, pagination
• Quick Actions: Links to settings, users, scheduled jobs, system logs

Data Sources

GET /api/admin/metrics

• Total requests (all time)
• Active downloads (status: 'downloading')
• Completed requests (status: 'downloaded' or 'available', last 30 days)
• Failed requests (status: 'failed', last 30 days)
• Total users
• System health indicators

GET /api/admin/downloads/active

• Request ID, title, progress %, speed, ETA, user

GET /api/admin/requests (Paginated)

• Query params: page, pageSize (10|25|50|100), search, status, userId, sortBy, sortOrder
• Returns: requests[], total, page, pageSize, totalPages
• Sorting: createdAt (default), completedAt, title, user, status
• Filtering: by status, by user, text search (title/author)

GET /api/admin/requests/recent (Legacy)

• Request ID, title, user, status, created/completed dates
• Limited to 50 entries, no filtering

GET /api/admin/requests/pending-approval

• Requests with status 'awaiting_approval', includes audiobook + user details
• Returns: requests array, count

POST /api/admin/requests/[id]/approve

• Action: 'approve' (set status to 'pending', trigger search) or 'deny' (set status to 'denied')
• Validates request is in 'awaiting_approval' status

GET /api/admin/users

• User ID, Plex ID, username, email, role, avatar, created/updated dates, last login, request count, autoApproveRequests

PUT /api/admin/users/[id]

• Update user role (user/admin), autoApproveRequests (true/false/null)
• Prevents self-demotion

GET /api/admin/settings/auto-approve

• Get global auto-approve setting (boolean)

PATCH /api/admin/settings/auto-approve

• Update global auto-approve setting (boolean)

GET /api/admin/logs

• Query params: page, limit, status, type, search, dateFrom, dateTo, hasError, userId, audiobookQuery
• limit: one of 25/50/100 (default 50; invalid values clamp to 50)
• status: 'all' or one of pending/active/completed/failed/delayed/stuck
• type: 'all' or any job type key
• dateFrom / dateTo: ISO UTC strings; invalid dates silently dropped
• hasError: 'true' or '1' → status in (failed, stuck) OR errorMessage IS NOT NULL
• userId: uuid → filters via request.userId
• audiobookQuery: free text → OR-contains (case-insensitive) on request.audiobook.{title,author}
• search: free text → 6-column OR: bullJobId (startsWith, case-sensitive), errorMessage (contains-i), events.some.message (contains-i), request.audiobook.title/author (contains-i), request.user.plexUsername (contains-i)
• hasError + search combine under top-level AND; other filters compose via AND on where
• Where-builder: exported buildLogsWhere(params) in route file (pure, testable)
• Returns: { logs, pagination: { page, limit, total, totalPages } }

Request Management Features

• Filter Bar:
  • Text search (title/author, 300ms debounce)
  • Status dropdown (all statuses)
  • User dropdown (all users)
  • Clear filters button
• Sortable Columns: Click headers to sort by title, user, status, requested, completed
• Pagination: Page navigation, page size selector (10/25/50/100), results count
• URL State: Filters/sort/page stored in URL query params (shareable, bookmarkable)
• Actions: Delete, cancel, manual search, fetch ebook (via dropdown)

Features

• Auto-refresh every 10 seconds (SWR)
• Back to Home button in header
• Admin role required
• Real-time progress updates
• Requests Awaiting Approval Section:
  • Only visible when pending approval requests exist
  • Grid layout (3 columns on desktop)
  • Book cards with cover, title, author, user info, timestamp
  • Approve (green) and Deny (red) buttons
  • Loading states during approval/denial actions
  • Toast notifications for success/errors
  • Mutates pending-approval, recent requests, metrics caches on action

Navigation

• /admin/jobs - Scheduled jobs management (trigger, edit schedule, enable/disable)
• /admin/settings - System settings (Plex, Prowlarr, paths)
• /admin/users - User management (view users, change roles)
• /admin/logs - System logs (view job history, errors, filter by status/type)

User Management Features

• List all users with avatar, email, role, request count, last login, autoApproveRequests
• Edit user roles (user/admin)
• Cannot change own role (security)
• Shows request count per user
• Role badges (purple for admin, gray for user)
• Global Auto-Approve Toggle:
  • Checkbox at top: "Auto-approve all requests by default"
  • Updates Configuration.auto_approve_requests
• Per-User Auto-Approve Control:
  • Dropdown: Use Global (null), Always Auto-Approve (true), Always Require Approval (false)
  • Updates User.autoApproveRequests
  • Shows effective setting (considers global + per-user)

System Logs Features

• Real-time job monitoring (10s SWR refresh; pauses on interact)
• Filter row (5 pickers): Status · Job Type · Date Range · User typeahead · Audiobook free-text
  • Status: dropdown over VALID_STATUSES (from src/app/admin/logs/types.ts); labels via STATUS_OPTIONS in src/lib/constants/log-filters.ts
  • Job Type: dropdown over JOB_TYPE_LABELS insertion order (src/lib/constants/job-labels.ts)
  • Date Range: presets (Last hour / 24h / 7d / 30d / Custom / All time) — default = Last 7 days (Zach #1); Custom uses <input type="datetime-local"> rendered as local time, wired as UTC ISO
  • User: typeahead via useUserSearch (fetch-once from /api/admin/users, SWR-cached, in-memory filter, max 10 suggestions); selection sets userId = User.id
  • Audiobook: free-text → server-side OR-contains on title/author (Zach #4 — no picker)
• Active filter chips: dismissable <button aria-label="Remove filter: X"> strip; NOT sticky (Zach #6 — scrolls with content). Errors-only renders as a chip when active.
• Clear all filters: visible only when ≥1 filter or the search input is non-default
• Pause-on-interact reasons (registered to useAutoRefreshControl):
  • logs-status-dropdown, logs-type-dropdown, logs-date-picker, logs-user-typeahead, logs-book-input
• URL = source of truth via useLogsUrlState (src/app/admin/logs/hooks/); param names exported as LOG_PARAMS; same names used by /api/admin/logs
• Shows related audiobook/user for request jobs
• Expandable error messages, duration calc, attempt tracking, Bull job ID
• Pagination: page-size selector (25 / 50 / 100), default 50

Tech Stack

• React Server Components + SWR
• Tailwind CSS
• Prisma aggregations for metrics
• Database queries with indexing