Admin Panel

Administrative dashboard for monitoring and managing your Guccho server

The Guccho admin panel provides comprehensive tools for server administrators to monitor metrics, manage users, moderate beatmaps, and review system logs. Access requires administrator privileges.

Admin panel features are only accessible to users with the admin role. Unauthorized access attempts will be rejected.

Admin Dashboard

The main dashboard displays real-time metrics across users, beatmaps, and scores with customizable time periods.

Admin Dashboard

View server metrics, user statistics, and activity trends

Metrics Overview

The dashboard organizes metrics into three main categories:

User Metrics

Total users, active users, and restricted accounts

Map Metrics

Total maps, ranked beatmaps, and custom content

Score Metrics

Total scores and recent submissions

Time Period Selection

Metrics can be viewed across different time periods:

• Daily - Last 24 hours (DAU - Daily Active Users)
• Weekly - Last 7 days (WAU - Weekly Active Users)
• Monthly - Last 30 days (MAU - Monthly Active Users)

The time period selector updates all metric cards simultaneously to show consistent data.

User Metrics

Total Users

Displays the total number of registered users and shows growth with new user count for the selected period.

• Total Count - All registered users in the database
• New Users - Users registered during the selected period (green text for positive growth)
• User Loss - Deleted accounts shown in warning color

Active Users

Shows active user count based on the selected time period:

• DAU - Daily Active Users (users active in last 24 hours)
• WAU - Weekly Active Users (users active in last 7 days)
• MAU - Monthly Active Users (users active in last 30 days)

Restricted Users

Displays currently restricted accounts that cannot participate in rankings or certain community features.

• Count - Total number of restricted accounts
• Status - Currently active restrictions

Map Metrics

Total Maps

All beatmaps in the database, including maps from osu! (Bancho) and custom uploads.

• Total - Complete beatmap count
• New Maps - Maps added during the selected period

Ranked Maps

Beatmaps with ranked status that count toward performance points (pp).

• Ranked Count - Maps eligible for ranking
• PP Calculation - These maps contribute to player rankings

Custom Maps

Beatmaps uploaded directly to Guccho rather than mirrored from osu!.

• Custom Count - Server-specific content
• Community Content - Maps created for your server

Score Metrics

Total Scores

All scores submitted across all game modes and beatmaps.

Recent Scores

Scores submitted during the selected time period, showing player activity levels.

User Management

The user management interface provides powerful search and filtering capabilities for finding and managing user accounts.

User Management

Search, filter, and manage user accounts

Search Parameters

Administrators can search users by multiple criteria:

id · string

User ID for direct lookup

name · string

Username or display name

safeName · string

Stable username used in profile links

email · string

Email address associated with the account

flag · CountryCode

Filter by country or region

roles · array

Filter by user roles (admin, moderator, etc.)

Search Results

User search results display in a paginated table with the following information:

• User Profile - Avatar, name, and country
• Roles - Badges showing assigned roles
• Email - Contact information (clickable mailto link)
• Registration Date - When the account was created
• Last Activity - Most recent user activity
• Actions - Link to detailed user management page

Pagination Controls

• Page Size - Configure results per page (1-20 users)
• Page Navigation - Jump to specific pages or use quick navigation
• Total Count - Shows total matching users

Example search configuration:

{
  page: 0,
  perPage: 10,
  name: "username",
  roles: [UserRole.Admin]
}

Individual User Management

Clicking “details” on a user opens their administrative profile page at /admin/users/[id] where you can:

• View detailed user statistics
• Modify user roles and permissions
• Review user activity
• Manage restrictions

Beatmap Management

The beatmap management interface allows administrators to moderate and update beatmap status.

Beatmap Management

Search and manage beatmap rankings

Beatmap Search

Search beatmaps using multiple criteria:

• Keyword - Search by beatmap ID, artist, title, version, or MD5 hash
• Game Mode - Filter by specific osu! game mode
• Player Requests - View beatmaps requested by players

Beatmap Information

Search results show detailed information for each beatmap:

1. Beatmapset Information

   • Set ID - Beatmapset identifier (links to osu! if from Bancho)
   • Artist - Song artist
   • Title - Song title (links to local beatmapset page)
   • Source - Origin (Bancho or custom upload)
2. Individual Beatmap Details

   • Version - Difficulty name
   • Beatmap ID - Individual difficulty identifier
   • MD5 Hash - File hash for verification
   • Vote Count - Player requests for this map
   • Status - Current ranking status

Ranking Status Management

Administrators can update beatmap ranking status:

• Graveyard - Inactive or abandoned beatmaps
• WIP - Work in progress
• Pending - Awaiting moderation
• Ranked - Approved for ranking (counts pp)
• Approved - Special category for marathon maps
• Qualified - In qualification period
• Loved - Community favorites (no pp)

Changing a beatmap to Ranked status allows it to contribute to performance points. Only rank beatmaps that meet quality standards.

Batch Updates

The interface supports batch operations:

1. Change status for multiple beatmaps
2. Review changes in the batch queue
3. Click “Save” to apply all changes at once

Beatmaps from osu! (Bancho) display with green links to the official website.

Logs and Monitoring

The logs page provides access to system logs for debugging and monitoring server health.

Server Logs

View and filter system logs

Log Filtering

Filter logs by multiple criteria:

loglevel · LogLevel

Minimum log level to display (0-6):

• 0: Trace
• 1: Debug
• 2: Info
• 3: Warn
• 4: Error
• 5: Fatal
• 6: Silent

last · number

Number of recent log entries to fetch (default: 50)

direction · 'asc' | 'desc'

Sort order for log entries (ascending or descending)

Log Display

Each log entry shows:

• Timestamp - When the event occurred (localized)
• Level - Log severity level
• Label - Log category or component
• Backend - Which backend service generated the log
• Message - Detailed log message

Log Management

Truncate Logs

Administrators can clear all logs using the “truncate” button. This action is irreversible and should be used carefully.

Truncating logs permanently deletes all log entries. Make sure to export any important logs before truncating.

Access Control

Admin panel access is restricted through middleware:

definePageMeta({
  middleware: 'admin',
})

Permission Levels

Users must have the admin role to access administrative features. The system checks:

1. User Authentication - Must be logged in
2. Role Verification - Must have admin privileges
3. Session Validity - Active session required

Unauthorized access attempts are redirected to the login page or show an error.

Role-Based Features

Different admin features may require different permission levels:

• Metrics Dashboard - Read-only admin access
• User Management - User moderation privileges
• Beatmap Management - Content moderation privileges
• System Logs - Full admin access

Best Practices

Regular Monitoring

• Check user metrics daily to track growth
• Monitor active user trends to gauge engagement
• Review restricted accounts periodically

Beatmap Moderation

• Only rank beatmaps that meet quality standards
• Respond to player beatmap requests promptly
• Review custom beatmaps before ranking

User Management

• Investigate unusual account activity
• Manage roles and permissions carefully
• Keep user data secure and private

System Maintenance

• Review logs regularly for errors
• Monitor server performance through metrics
• Keep log levels appropriate for production

Implementation Reference

The admin panel is implemented across these files:

• src/pages/admin/index.vue - Main dashboard with metrics
• src/pages/admin/users/index.vue - User search and management
• src/pages/admin/users/[id]/index.vue - Individual user details
• src/pages/admin/beatmaps.vue - Beatmap search and status management
• src/pages/admin/logs.vue - Log viewer and management

All admin endpoints use tRPC with authentication and authorization checks.

The admin panel uses reactive data fetching with automatic updates when filters change. Loading states and error handling are built into all components.