Admin Roles & Permissions System

Overview

This document describes the role hierarchy and permission system for managing site operations, employees, and access control.

Role Hierarchy

Owner > Admin > Moderator > Standard

Role Definitions

1. Owner (You - Site Owner)

   • Full access to everything
   • Can manage system settings
   • Can manage employees and permissions
   • Cannot be demoted or banned
   • Bypasses all permission checks

2. Admin (Your Employees)

   • Can manage users, content, tournaments, events
   • Can ban users
   • Can approve/reject tournaments and events
   • Can manage regulations and reference data
   • Cannot modify system settings
   • Cannot manage other admins' permissions
   • Has permissions by default (unless explicitly denied)

3. Moderator (Content Moderators)

   • Can moderate content (posts, comments)
   • Can review AI-flagged content
   • Can view audit logs (if granted permission)
   • Cannot ban users
   • Cannot manage users
   • Cannot approve tournaments
   • Needs explicit permissions granted

4. Standard (Regular Users)

   • No admin access
   • Regular user features only

Permission System

Granular Permissions

Instead of just roles, you can grant specific permissions to employees:

User Management:

• Users.View - View user list
• Users.Edit - Edit user details
• Users.Ban - Ban users
• Users.Unban - Unban users
• Users.Delete - Delete users
• Users.ChangeRole - Change user roles

Content Moderation:

• Content.Moderate - Moderate content
• Content.Delete - Delete content
• Content.Approve - Approve content

Tournament Management:

• Tournaments.View - View tournaments
• Tournaments.Approve - Approve tournaments
• Tournaments.Reject - Reject tournaments
• Tournaments.Suspend - Suspend tournaments

Organizer Management:

• Organizers.View - View organizers
• Organizers.Verify - Verify organizers
• Organizers.Suspend - Suspend organizers

Event Management:

• Events.View - View events
• Events.Approve - Approve events
• Events.Reject - Reject events

Regulations:

• Regulations.View - View regulations
• Regulations.Edit - Edit regulations

Reference Data:

• Brands.Manage - Manage brands
• Species.Manage - Manage fish species
• Lookups.Manage - Manage lookup tables

System Settings (Owner Only):

• Settings.View - View system settings
• Settings.Modify - Modify system settings
• Settings.Delete - Delete system settings

Announcements:

• Announcements.Create - Create announcements
• Announcements.Edit - Edit announcements
• Announcements.Delete - Delete announcements

Audit Logs:

• AuditLogs.View - View audit logs
• AuditLogs.Export - Export audit logs

Employee Management (Owner Only):

• Employees.Manage - Manage employees
• Permissions.Manage - Manage permissions

New Admin Features

1. AdminSystemSettingsController (/api/admin/system-settings)

Owner Only - Manage site-wide configuration

Features:

• Create/update/delete system settings
• Hide sensitive values (API keys, passwords)
• Track who changed what
• Categorize settings (General, Features, Integrations, Email)
• Mark settings that require app restart

Example Settings:

• SiteName - Site name
• MaintenanceMode - Enable/disable maintenance mode
• MaxFileUploadSize - Maximum file upload size
• StripeApiKey - Stripe API key (sensitive)
• EmailSmtpHost - Email server settings
• FeatureFlags - JSON for feature flags

2. AdminEmployeeController (/api/admin/employees)

Owner Only - Manage employees and their permissions

Features:

• View all admin/moderator employees
• Grant/revoke specific permissions
• Change employee roles
• View permission history
• Set restrictions (e.g., max ban duration)

Use Cases:

• Hire a content moderator → Grant Content.Moderate permission
• Hire a tournament manager → Grant Tournaments.Approve permission
• Restrict an admin → Revoke Users.Delete permission
• Promote moderator to admin → Change role

3. AdminAuditLogController (/api/admin/audit-logs)

Requires Permission - View audit logs

Features:

• Track all admin actions
• See who did what and when
• Filter by action, user, date range
• View statistics (most active admins, common actions)
• IP address and user agent tracking

Tracked Actions:

• User bans/unbans
• Tournament approvals/rejections
• Setting changes
• Permission grants/revocations
• Content moderation actions

4. AdminAnnouncementController (/api/admin/announcements)

Requires Permission - Create site-wide announcements

Features:

• Create banners/notifications
• Schedule announcements (start/end dates)
• Target specific user tiers
• Dismissible or persistent
• Priority levels (Low, Normal, High, Critical)
• Types (Info, Success, Warning, Error)

Use Cases:

• "Site maintenance scheduled for Sunday"
• "New feature: Tournament registration!"
• "Important: Terms of Service updated"

Authorization Attributes

[AdminOnly]

• Allows Admin and Owner
• Use for general admin endpoints

[OwnerOnly]

• Only allows Owner
• Use for system settings, employee management

[RequirePermission("Permission.Name")]

• Checks specific permission
• Owner bypasses check
• Admin has permission by default (unless denied)
• Moderator needs explicit grant

Example:

[RequirePermission(Permissions.UsersBan)]
public async Task<ActionResult> BanUser(...)
{
    // Only users with Users.Ban permission can access
}

Employee Management Workflow

Hiring a Content Moderator

1. Create user account (or use existing)
2. Change role to Moderator:

   PUT /api/admin/employees/{userId}/role
   { "role": "Moderator" }

3. Grant permissions:

   POST /api/admin/employees/{userId}/permissions
   {
     "permission": "Content.Moderate",
     "isGranted": true
   }

Hiring a Tournament Manager

1. Create user account
2. Change role to Admin:

   PUT /api/admin/employees/{userId}/role
   { "role": "Admin" }

3. Grant tournament permissions:

   POST /api/admin/employees/{userId}/permissions
   {
     "permission": "Tournaments.Approve",
     "isGranted": true
   }

4. Optionally deny other permissions:

   POST /api/admin/employees/{userId}/permissions
   {
     "permission": "Users.Delete",
     "isGranted": false  // Explicitly deny
   }

Security Features

Audit Logging

• All admin actions are logged
• Tracks: who, what, when, why, IP address
• Cannot be deleted (compliance)
• Exportable for compliance reports

Permission Restrictions

• Can set restrictions on permissions (JSON)
• Example: {"maxBanDurationDays": 7} for Users.Ban
• Prevents abuse of permissions

Role Protection

• Cannot remove last admin
• Cannot change owner role
• Cannot ban owner

Best Practices

1. Start with Roles, Add Permissions as Needed

   • Most admins can use default Admin role
   • Only grant specific permissions when restrictions needed

2. Use Moderator Role for Content-Only Access

   • Moderators can't ban users or manage system
   • Perfect for community moderators

3. Audit Regularly

   • Review audit logs weekly
   • Check for unusual activity
   • Monitor permission grants

4. Document Permission Changes

   • Use Reason field when granting/revoking
   • Helps track why permissions were changed

5. Use System Settings for Configuration

   • Don't hardcode values
   • Easy to change without deployment
   • Track changes in audit log

Migration Path

When you're ready to add employees:

1. Set yourself as Owner:

   UPDATE "Users" SET "Role" = 5 WHERE "Email" = 'your@email.com';

2. Create employee accounts (or promote existing users)

3. Assign roles via AdminEmployeeController

4. Grant permissions as needed

5. Monitor via audit logs

Summary

You now have:

• ✅ Role hierarchy (Owner > Admin > Moderator)
• ✅ Granular permissions for fine-grained control
• ✅ Employee management for assigning roles/permissions
• ✅ Audit logging for compliance and security
• ✅ System settings for site configuration
• ✅ Announcements for site-wide messaging

This gives you full control over your site and employees, with the flexibility to grant exactly the permissions each employee needs.