Skip to main content

ARC // OS — Admin Guide

Last Updated: 2026-01-23
Audience: Platform Administrators

Overview​

The Admin Dashboard provides platform administrators with tools to manage the platform, view analytics, handle reports, and manage time-sensitive global content. CRITICAL: Admins CANNOT see user content—privacy is paramount.

Key Principles​

  • Privacy-first: Admins can see aggregate analytics but NEVER individual user content (tasks, journal entries, meals, etc.)
  • Time-sensitive management: Only manage global tables that need real-time updates (seasonal events, active challenges, etc.)
  • Migrations for static data: Most global content (opponents, achievements, shop items) should be managed via migrations, not admin UI
  • Transparency: All admin actions are logged for audit purposes
  • Minimal scope: Keep admin features focused—don't over-engineer

Getting Started​

Accessing the Admin Dashboard​

  1. Ensure you have admin access - Only existing admins can grant admin access to other users
  2. Navigate to Admin Dashboard - Click the Shield icon (🛡️) in the main navigation menu
  3. Admin routes are protected - Non-admins are automatically redirected away from /admin/* routes

Admin Role System​

Granting Admin Access:

  • Only existing admins can grant admin access
  • Use the Admin Dashboard → Admin Management section
  • Search for user by email or public ID
  • Grant access via API endpoint: POST /api/v1/admin/users/:userId/grant

Revoking Admin Access:

  • Only existing admins can revoke admin access
  • Cannot revoke your own admin access (safety measure)
  • Revoke access via API endpoint: POST /api/v1/admin/users/:userId/revoke

Viewing All Admins:

  • Admin Dashboard shows a paginated list of all admins
  • Displays email and date when admin access was granted
  • Accessible via: GET /api/v1/admin/users/admins

Admin Features​

1. Analytics Dashboard​

Location: /admin/analytics

Purpose: View platform-wide statistics and metrics (aggregate data only, no individual user data)

Available Metrics:

Platform Statistics:

  • Total users
  • Active users (30 days)
  • New signups (30 days)
  • Email verified users
  • Onboarding completed users
  • Users with public ID

Gamification Statistics:

  • Total XP awarded (platform-wide)
  • Coins in circulation
  • Achievements unlocked (count)
  • Titles awarded (count)
  • Shop items purchased (count)

Activity Statistics:

  • Tasks completed (total)
  • Training sessions logged (total)
  • Cardio sessions logged (total)
  • Checklist items completed (total)
  • Journal entries created (total)

Engagement Statistics:

  • Daily active users (DAU)
  • Weekly active users (WAU)
  • Monthly active users (MAU)
  • Average sessions per user
  • Retention metrics

Subscription Statistics:

  • Total free users
  • Total subscribed users
  • Conversion rate
  • Active subscriptions
  • Canceled subscriptions

Features:

  • Real-time statistics
  • Visual charts and graphs
  • Platform user breakdown charts
  • Gamification activity charts

API Endpoints:

  • GET /api/v1/admin/analytics/platform - Platform statistics
  • GET /api/v1/admin/analytics/gamification - Gamification statistics
  • GET /api/v1/admin/analytics/activity - Activity statistics
  • GET /api/v1/admin/analytics/engagement - Engagement metrics
  • GET /api/v1/admin/analytics/subscriptions - Subscription metrics

Future Enhancements:

  • Date range filters
  • Export functionality (CSV/JSON)

2. Seasonal Events Management​

Location: /admin/seasonal

Purpose: Manage seasonal events that link shop items, challenges, and achievements

Features:

Event Management:

  • Create new seasonal events
  • Edit existing events (name, description, dates, active status)
  • Delete events
  • View all events (active and inactive)

Event Details:

  • Event name and description
  • Start date and end date
  • Active status (toggle on/off)
  • Linked shop items (view and manage)
  • Linked challenges (view and manage)
  • Linked achievements (view and manage)

Linking Content:

  • Search and link shop items to events (bulk operations)
  • Search and link challenges to events (bulk operations)
  • Search and link achievements to events (bulk operations)
  • View all linked content in expandable details view

Use Cases:

  • Holiday events (Christmas, Halloween, etc.)
  • Special promotions
  • Limited-time challenges
  • Seasonal shop items

API Endpoints:

  • GET /api/v1/admin/seasonal/events - List all events
  • GET /api/v1/admin/seasonal/events/:eventId - Get event by ID
  • POST /api/v1/admin/seasonal/events - Create event
  • PUT /api/v1/admin/seasonal/events/:eventId - Update event
  • DELETE /api/v1/admin/seasonal/events/:eventId - Delete event
  • POST /api/v1/admin/seasonal/events/:eventId/shop-items - Link shop items
  • POST /api/v1/admin/seasonal/events/:eventId/challenges - Link challenges
  • POST /api/v1/admin/seasonal/events/:eventId/achievements - Link achievements

Event Templates:

  • Seasonal events can be created from templates for recurring holidays
  • Templates define: key prefix, name, description, month/day, duration
  • System automatically creates events from templates when within 30 days
  • Use ensureRecurringEvents() to check and create upcoming events
  • Templates are managed in code (not via admin UI) for consistency

Best Practices:

  • Create events well in advance of their start date
  • Test event activation before the event starts
  • Link all relevant content before activating
  • Deactivate events after they end
  • Use templates for recurring holidays (Christmas, Halloween, etc.)

3. Global Content Management​

Location: /admin/global

Purpose: Manage time-sensitive global content that needs real-time activation/deactivation

Important Note: Static global content (opponents, achievements, shop items) should NOT be managed here—use database migrations instead.

Manageable Content:

Global Challenges:

  • Activate/deactivate global challenges
  • Toggle switches for each challenge
  • View active and inactive challenges

Global Bounties:

  • Activate/deactivate global bounties
  • Toggle switches for each bounty
  • View active and inactive bounties

One-Time Events:

  • Create one-time events (launch events, milestones, exclusive celebrations)
  • Update one-time events
  • Delete one-time events
  • List all one-time events
  • Events can have automatic milestone detection
  • Events can have exclusive rewards (XP, coins, materials, achievements)
  • Events are one-time only (never repeat, unlike seasonal events)

Features:

  • Simple toggle switches for challenges and bounties
  • Create/edit forms for one-time events
  • Clear indication of active vs inactive content
  • Warning about static content management

API Endpoints:

  • GET /api/v1/admin/global/challenges - List all global challenges
  • GET /api/v1/admin/global/bounties - List all global bounties
  • GET /api/v1/admin/global/one-time-events - List all one-time events
  • POST /api/v1/admin/global/challenges/:challengeId/toggle - Toggle challenge
  • POST /api/v1/admin/global/bounties/:bountyId/toggle - Toggle bounty
  • POST /api/v1/admin/global/one-time-events - Create one-time event
  • PUT /api/v1/admin/global/one-time-events/:eventId - Update one-time event
  • DELETE /api/v1/admin/global/one-time-events/:eventId - Delete one-time event

When to Use:

  • Activating challenges for special events
  • Enabling bounties for limited-time promotions
  • Creating one-time events (announcements, special occasions)
  • Managing content that needs to be turned on/off quickly

When NOT to Use:

  • Creating new opponents (use migrations)
  • Adding new achievements (use migrations)
  • Adding shop items (use migrations)
  • Modifying static game content (use migrations)

4. User Rewards System​

Location: /admin/rewards

Purpose: Award XP, coins, achievements, and titles to users (for support, compensation, special events, etc.)

Features:

User Search:

  • Search by email or public ID
  • View user information (email, public ID)
  • View user's current gamification stats (level, XP, coins)

Reward Types:

  • XP - Award experience points (with amount and reason)
  • Coins - Award coins (with amount and reason)
  • Achievement - Award achievement (by achievement key, with reason)
  • Title - Award title (by title key, with reason)

Reward History:

  • View all rewards given to a user
  • See who awarded the reward (admin ID)
  • See when the reward was awarded
  • See the reason for the reward

Important:

  • All reward actions are logged with admin ID and reason
  • Rewards are tracked in reward history
  • Users can see admin-granted rewards in their gamification stats
  • CRITICAL: Only displays gamification stats, no user content

API Endpoints:

  • GET /api/v1/admin/users/search?query=<email|publicId> - Search for user
  • POST /api/v1/admin/users/:userId/rewards/xp - Award XP
  • POST /api/v1/admin/users/:userId/rewards/coins - Award coins
  • POST /api/v1/admin/users/:userId/rewards/achievement - Award achievement
  • POST /api/v1/admin/users/:userId/rewards/title - Award title
  • GET /api/v1/admin/users/:userId/rewards/history - Get reward history

Best Practices:

  • Always provide a clear reason when awarding rewards
  • Use rewards for compensation, support, or special events
  • Document why rewards were given (reason field)
  • Review reward history regularly

Example Use Cases:

  • Compensating users for bugs or issues
  • Rewarding users for reporting bugs
  • Special event participation rewards
  • Support compensation

5. Reports Management​

Location: /admin/reports

Purpose: Manage user reports (bug reports, abuse reports, feature requests, etc.)

Features:

Report Types:

  • Bug Reports - Technical issues, bugs, errors
  • Abuse Reports - User abuse, harassment, inappropriate content
  • Feature Requests - Suggestions for new features
  • Other - Miscellaneous reports

Report Status:

  • Pending - New reports awaiting review
  • Resolved - Reports that have been addressed
  • Dismissed - Reports that were reviewed but not actionable

Report Management:

  • View all reports with filters (by status, by type)
  • View report details (metadata, description, reporter, date)
  • Resolve reports (with resolution notes)
  • Dismiss reports (with dismissal reason)
  • View report statistics

Report Statistics:

  • Total reports
  • Pending reports
  • Resolved reports
  • Dismissed reports
  • Reports by type
  • Reports by status

Important:

  • CRITICAL: Reports do NOT expose user content—only metadata (user IDs, report type, description)
  • All report actions are logged
  • Resolution and dismissal reasons are required

API Endpoints:

  • GET /api/v1/admin/reports - List reports (with status filter)
  • GET /api/v1/admin/reports/:reportId - Get report details
  • GET /api/v1/admin/reports/stats - Get report statistics
  • POST /api/v1/admin/reports/:reportId/resolve - Resolve report
  • POST /api/v1/admin/reports/:reportId/dismiss - Dismiss report

Workflow:

  1. Review pending reports regularly
  2. Investigate reports (check metadata, not user content)
  3. Resolve or dismiss with clear reasons
  4. Track resolution patterns for common issues

6. Admin Action Logs​

Location: /admin/logs

Purpose: View audit trail of all admin actions for accountability and transparency

Features:

Action Logging:

  • All admin actions are automatically logged
  • Logs include: admin ID, action type, target type, target ID, details, timestamp
  • Immutable audit trail (logs cannot be deleted)

Filtering:

  • Filter by admin (who performed the action)
  • Filter by action type (what action was performed)
  • Filter by target type (what was affected)
  • Filter by date range
  • Search by target ID

Action Types:

  • grant_admin - Admin access granted
  • revoke_admin - Admin access revoked
  • award_xp - XP awarded to user
  • award_coins - Coins awarded to user
  • award_achievement - Achievement awarded to user
  • award_title - Title awarded to user
  • resolve_report - Report resolved
  • dismiss_report - Report dismissed
  • toggle_challenge - Challenge activated/deactivated
  • toggle_bounty - Bounty activated/deactivated
  • create_event - Event created
  • update_event - Event updated
  • delete_event - Event deleted

API Endpoints:

  • GET /api/v1/admin/logs - Get action logs (with filters)
  • GET /api/v1/admin/logs/:logId - Get specific action log

Use Cases:

  • Audit trail for compliance
  • Debugging admin actions
  • Understanding platform changes
  • Accountability and transparency

Security & Privacy​

Privacy Enforcement​

CRITICAL RULES:

  • Admins can NEVER see individual user content (tasks, journal entries, meals, etc.)
  • Analytics show ONLY aggregate data
  • Reports show ONLY metadata (not user content)
  • User rewards only show gamification stats (not user content)
  • Backend enforces privacy—never returns user content to admins

Access Control​

Admin Access:

  • Only existing admins can grant/revoke admin access
  • Admin routes are protected with requireAdmin() middleware
  • Frontend route guard redirects non-admins away from /admin/* routes

Action Logging:

  • All admin actions are logged with admin ID, action, target, and reason
  • Logs are immutable (cannot be deleted)
  • Logs provide full audit trail

Rate Limiting​

  • Admin routes should have appropriate rate limiting
  • Prevents abuse of admin endpoints
  • Configurable via environment variables

Troubleshooting​

Common Issues​

Issue: Cannot access admin dashboard

  • Solution: Verify you have admin access. Check isAdmin field in user record. Only existing admins can grant access.

Issue: Analytics not loading

  • Solution: Check backend logs for errors. Verify database connection. Ensure admin routes are properly registered.

Issue: Cannot grant admin access

  • Solution: Only existing admins can grant admin access. Verify you're logged in as an admin. Check that the target user exists.

Issue: Reports not showing

  • Solution: Check report filters. Verify reports exist in database. Check backend logs for errors.

Issue: Seasonal events not activating

  • Solution: Verify event dates are correct. Check that event is marked as active. Ensure linked content exists.

Issue: Rewards not applying

  • Solution: Verify user exists. Check reward amount/type is valid. Review backend logs for errors. Check reward history to confirm action was logged.

Issue: Action logs not appearing

  • Solution: Verify action was actually performed. Check filters are correct. Ensure logs are being written to database.

Debugging Steps​

  1. Check Admin Status:

    • Verify isAdmin field in user record
    • Test admin access via GET /api/v1/admin/status

  2. Check Backend Logs:

    • Review server logs for errors
    • Check for authentication/authorization failures
    • Verify database queries are executing

  3. Check Frontend:

    • Verify admin routes are accessible
    • Check browser console for errors
    • Verify API calls are being made

  4. Check Database:

    • Verify data exists in database
    • Check foreign key relationships
    • Verify admin actions are being logged

Getting Help​

If you encounter issues:

  1. Check this troubleshooting guide
  2. Review backend logs
  3. Check action logs for recent admin actions
  4. Verify admin access is correct
  5. Contact platform maintainers if issue persists

Best Practices​

Admin Access Management​

  • Grant access carefully - Only grant admin access to trusted users
  • Review admin list regularly - Remove access for users who no longer need it
  • Use principle of least privilege - Only grant admin access when necessary
  • Document admin access - Keep track of who has admin access and why

Analytics​

  • Review regularly - Check analytics dashboard weekly
  • Monitor trends - Watch for unusual patterns
  • Use aggregate data - Never try to access individual user data
  • Export when needed - Use export functionality (when available) for reporting

Seasonal Events​

  • Plan ahead - Create events well in advance
  • Test before activation - Verify events work before activating
  • Link content early - Link shop items, challenges, achievements before activation
  • Deactivate after end - Deactivate events after they end

Global Content​

  • Use migrations for static content - Don't manage static content via admin UI
  • Only manage time-sensitive content - Use admin UI only for content that needs real-time updates
  • Document changes - Note why content was activated/deactivated

User Rewards​

  • Always provide reasons - Document why rewards were given
  • Use sparingly - Only award rewards when appropriate
  • Review history - Check reward history regularly
  • Be transparent - Users can see admin-granted rewards

Reports​

  • Respond promptly - Review and respond to reports quickly
  • Document resolutions - Always provide clear resolution notes
  • Track patterns - Identify common issues from reports
  • Follow up - Verify resolutions when possible

Action Logs​

  • Review regularly - Check action logs for unusual activity
  • Use for debugging - Action logs help debug issues
  • Maintain audit trail - Keep logs for compliance and accountability

API Reference​

Admin Endpoints​

All admin endpoints are prefixed with /api/v1/admin and require admin authentication.

Authentication:

  • Admin endpoints require JWT authentication (httpOnly cookie)
  • User must have isAdmin: true in database
  • Non-admins receive 403 Forbidden response

Common Endpoints:

  • GET /api/v1/admin/status - Check if current user is admin
  • GET /api/v1/admin/users/admins - List all admins
  • POST /api/v1/admin/users/:userId/grant - Grant admin access
  • POST /api/v1/admin/users/:userId/revoke - Revoke admin access

See API Documentation for complete endpoint reference.

Support​

For admin-related questions or issues:

  1. Review this guide
  2. Check action logs for recent changes
  3. Review backend logs for errors
  4. Contact platform maintainers

Remember: Admin access is a privilege. Use it responsibly and always prioritize user privacy.