TurboTrades/docs/ADMIN_DEBUG_PANEL.md

Admin Debug Panel Documentation

Overview

The Admin Debug Panel is a comprehensive testing and debugging tool integrated into the admin dashboard. It consolidates all system testing, diagnostics, and troubleshooting features in one centralized location.

Location

Access the debug panel at: Admin Dashboard → Debug Tab

Or directly at: /admin (scroll to Debug section)

Features

🔐 Auth & Connectivity Tab

Tests authentication status and backend connectivity.

Authentication Status

• Logged In - Current authentication state
• Username - Current user's display name
• Steam ID - User's Steam ID
• Staff Level - Permission level (0-5)
• Is Admin - Admin status (staffLevel >= 3)
• Balance - Current account balance

Backend Connectivity Tests

Automated tests that run on panel load:

1. Health Check - Verifies backend is running
2. Auth Check - Validates user session and cookies
3. Admin Config Access - Tests admin endpoint access
4. Admin Routes Access - Tests user management routes

Quick Actions

• Refresh Auth - Reload user authentication data
• Clear Cache - Clear localStorage and sessionStorage
• Test Admin Route - Quick test of admin config endpoint
• Copy Debug Info - Copy all debug data to clipboard (JSON format)

Environment Info

• API Base URL
• Current Route
• Window Location
• User Agent

📢 Announcements Tab

Test and debug announcement system functionality.

Status Display

• Total Loaded - Number of announcements fetched
• Active - Announcements passing all filters
• Dismissed - Count of dismissed announcements

Announcement List

Shows all announcements with detailed information:

• Type Badge - Info, Warning, Success, or Error
• Enabled Status - ✅ Enabled or ❌ Disabled
• Dismissible Status - 👋 Dismissible or 🔒 Permanent
• Message - Full announcement text
• Metadata - ID, start date, end date, dismissed status

Test Actions

• Reload - Refresh announcements from API
• Clear Dismissed - Remove dismissed IDs from localStorage
• Test API - Direct fetch test bypassing axios

API Response Viewer

Shows raw JSON response from last API call for debugging

🔧 Maintenance Tab

Test maintenance mode functionality and admin bypass.

Maintenance Status Card

Large visual indicator showing:

• Current maintenance state (Active ⚠️ or Operational ✅)
• Maintenance message
• Color-coded based on status

Status Information

• Maintenance Enabled - Current state
• Scheduled End - When maintenance will end (if scheduled)
• Whitelisted Users - Count of Steam IDs allowed during maintenance

Test Actions

• Reload - Refresh maintenance status
• Test Admin Bypass - Verify admin can access during maintenance
• Test User Block - Instructions to test non-admin blocking

Test Results

Shows results of maintenance tests with pass/fail indicators

⚙️ System Tab

(Future expansion for system-wide diagnostics)

Planned features:

• WebSocket connection status
• Market price updates
• Steam bot status
• Database connection health
• Cache statistics
• Performance metrics

Using the Debug Panel

Basic Workflow

1. Navigate to Admin Dashboard

   http://localhost:5173/admin
   

2. Click Debug Tab

   • Automatically runs connectivity tests
   • Displays current auth status

3. Switch Between Tabs

   • Each tab auto-loads relevant data
   • Tests run automatically where applicable

4. Run Manual Tests

   • Click action buttons to run specific tests
   • View results in real-time
   • Check console for detailed logs

Testing Announcements

1. Navigate to Announcements Tab
2. Check Status Metrics
   • Verify announcements are loaded
   • Check active count vs total
3. Review Announcement List
   • Ensure enabled state is correct
   • Verify date ranges
   • Check for dismissed badges
4. Test Actions
   • Clear dismissed to reset state
   • Test API directly to bypass axios
5. Check Console Logs
   • Look for "📡 Debug: Fetching announcements..."
   • Verify "✅ Debug: Loaded announcements"
6. Compare with Frontend
   • Navigate to home page
   • Verify announcements display correctly

Testing Maintenance Mode

1. Navigate to Maintenance Tab
2. Check Current Status
   • View status card color
   • Read maintenance message
3. Test Admin Bypass
   • Click "Test Admin Bypass"
   • Should show success ✅
   • Verify admin can still make API calls
4. Test User Block
   • Open incognito window
   • Navigate to site
   • Should see maintenance page
5. Toggle Maintenance
   • Go back to Config tab
   • Enable/disable maintenance
   • Return to Debug → Maintenance tab
   • Click reload to verify changes

Debugging Issues

Problem: Announcements Not Showing

1. Go to Debug → Announcements tab
2. Check "Total Loaded" count
3. If 0:
   • Click "Test API" button
   • Check API Response section
   • Look for errors in response
   • Verify backend is running
4. If loaded but not active:
   • Check announcement list for disabled badges
   • Verify dates (may be expired or not started)
   • Check if dismissed
5. Check browser console for errors

Problem: Admin Actions Blocked During Maintenance

1. Go to Debug → Maintenance tab
2. Verify maintenance is enabled
3. Click "Test Admin Bypass"
4. If fails:
   • Check Auth tab for admin status
   • Verify staffLevel >= 3
   • Check backend logs for maintenance middleware
   • Verify cookies/tokens are valid
5. Check Auth & Connectivity tab
6. Run "Test Admin Route"
7. Review error messages

Problem: Auth Not Working

1. Go to Debug → Auth & Connectivity tab
2. Check "Logged In" status
3. Run "Run All Tests" button
4. Review each test result:
   • Health Check - backend connectivity
   • Auth Check - session validity
   • Admin Config - permission check
5. Click "Refresh Auth" to reload
6. If still failing:
   • Check cookies in browser DevTools
   • Clear cache and re-login
   • Check backend logs

Console Logging

The debug panel outputs detailed console logs:

Announcements

🔵 Debug: AnnouncementBanner mounted
📡 Debug: Fetching announcements...
✅ Debug: Loaded announcements: [...]

Maintenance

✅ Admin [username] bypassing maintenance mode for /api/admin/config
⚠️ Blocking request during maintenance: /api/market/listings

Tests

📡 Response: { success: true, ... }
✅ Test passed: Health Check
❌ Test failed: Admin Config Access

Quick Reference

Color Codes

Color	Meaning	Example
🟢 Green	Success / Active	Logged in, test passed
🔴 Red	Error / Failed	Not authenticated, test failed
🟡 Yellow	Warning	Maintenance active
🔵 Blue	Info	Loading, running
⚪ Gray	Pending	Test not run yet

Staff Levels

Level	Role	Color	Access
0	User	Gray	Standard user
1	Staff	Orange	Basic staff tools
2	Moderator	Green	Moderation tools
3	Admin	Blue	Full admin access
4-5	Super Admin	Purple	System-level access

Common Actions

Action	Shortcut	Result
Reload Tab Data	Click reload button	Refreshes current tab data
Run All Tests	Click "Run All Tests"	Runs connectivity suite
Clear Cache	Click "Clear Cache"	Clears all storage
Copy Debug Data	Click "Copy Debug Info"	JSON to clipboard

Best Practices

When to Use Debug Panel

✅ Use debug panel for:

• Testing new features before release
• Diagnosing user-reported issues
• Verifying admin functionality
• Checking maintenance mode setup
• Troubleshooting API connectivity
• Validating authentication flow

❌ Don't use debug panel for:

• Production monitoring (use proper monitoring tools)
• Performance profiling (use browser DevTools)
• Database queries (use backend tools)
• Security testing (use penetration testing tools)

Debugging Workflow

1. Identify Issue - What's not working?
2. Check Relevant Tab - Auth, Announcements, or Maintenance
3. Review Status - Check metrics and indicators
4. Run Tests - Use action buttons to test
5. Check Logs - Browser console and backend logs
6. Copy Debug Info - Save state for later analysis
7. Fix Issue - Make necessary changes
8. Re-test - Verify fix with debug panel

Sharing Debug Info

When reporting issues or asking for help:

1. Click "Copy Debug Info" button
2. Paste into text editor
3. Add relevant console errors
4. Include backend logs if available
5. Note reproduction steps
6. Share with team

Troubleshooting

Debug Panel Not Loading

• Clear browser cache (Ctrl+Shift+R)
• Check browser console for errors
• Verify you're logged in as admin (staffLevel >= 3)
• Try restarting frontend dev server

Tests Timing Out

• Check backend is running (npm run dev)
• Verify port 3000 is accessible
• Check firewall/antivirus settings
• Try increasing axios timeout

Data Not Refreshing

• Click reload button on specific tab
• Run "Refresh Auth" in quick actions
• Clear cache and reload page
• Check WebSocket connection status

Future Enhancements

Planned features for future versions:

• Real-time Monitoring - Live stats and metrics
• WebSocket Tester - Test WS connections
• Database Query Tool - Run safe queries from panel
• Log Viewer - Backend logs in panel
• Performance Metrics - Response times, load stats
• Export Reports - Save debug sessions as files
• Scheduled Tests - Auto-run tests periodically
• Alert System - Notify when tests fail

Security Notes

• Debug panel is admin-only (requires staffLevel >= 3)
• Sensitive data (passwords, keys) never displayed
• Actions are logged for audit trail
• No direct database access from panel
• All tests use authenticated endpoints
• Panel disabled in production builds (optional)

API Endpoints Used

The debug panel tests these endpoints:

GET  /api/health                      - Health check
GET  /api/auth/me                     - Auth status
GET  /api/admin/config                - Admin config
GET  /api/admin/users/search          - User search
GET  /api/config/announcements        - Announcements
GET  /api/config/public               - Public config

Related Documentation

• Maintenance Mode Guide
• Announcements System
• Admin Panel Overview
• Banned Page

Support

If you encounter issues with the debug panel:

1. Check this documentation first
2. Review console logs for errors
3. Copy debug info to clipboard
4. Report to development team with:
   • Debug info JSON
   • Console errors
   • Steps to reproduce
   • Expected vs actual behavior

---

Last Updated: January 2024
Version: 1.0.0
Maintainer: Development Team