Skip to main content

Admin Control Panel - Design Document

Overview​

This document describes the admin control panel implementation for FishingLog. The panel is designed with a user-centric approach, focusing on what admins need to accomplish rather than technical database operations.

Difficulty Assessment: MODERATE ✅​

Why It's Moderate (Not Hard):​

  1. Existing Infrastructure Helps:

    • ✅ Hybrid enum/lookup system already supports dynamic enum extensions
    • ✅ Authorization helpers (AuthorizationHelper.IsAdminAsync()) exist
    • ✅ Clean entity structure with well-defined relationships
    • ✅ Existing controller patterns to follow

  2. What Makes It Moderate:

    • Need to create multiple controllers for different entity types
    • Need to implement proper authorization checks
    • Need to design user-friendly APIs (not just CRUD)
    • Need to handle edge cases (e.g., preventing deletion of last admin)

  3. What Makes It Easier:

    • LookupTable system means enum management is already database-driven
    • No need to modify enums in code - just add to lookup tables
    • Existing patterns for pagination, filtering, etc.

Architecture​

Authorization​

AdminOnlyAttribute - Custom authorization attribute that:

  • Checks if user has UserRole.Admin
  • Returns ForbidResult if not admin
  • Can be applied to controllers or individual endpoints
[AdminOnly]
public class AdminBrandController : ControllerBase
{
    // All endpoints require admin role
}

Controllers Created​

1. AdminLookupController (/api/admin/lookups)​

Manages lookup table values (enum extensions).

User-Centric Features:

  • Get all categories (e.g., "RodMaterial", "KnotCategory")
  • Get/Add/Update/Delete lookup values
  • Reorder lookup values (drag-and-drop support)
  • Prevents deletion of system-defined values

Key Endpoints:

  • GET /api/admin/lookups/categories - List all lookup categories
  • GET /api/admin/lookups/category/{category} - Get all values for a category
  • POST /api/admin/lookups - Add new lookup value
  • PUT /api/admin/lookups/{id} - Update lookup value
  • DELETE /api/admin/lookups/{id} - Delete lookup value (soft delete)
  • POST /api/admin/lookups/reorder - Reorder values

2. AdminBrandController (/api/admin/brands)​

Manages brands (gear manufacturers).

User-Centric Features:

  • Full CRUD operations
  • Record brand acquisitions (when one brand buys another)
  • Soft delete (deactivate) instead of hard delete
  • Prevents deletion of brands in use

Key Endpoints:

  • GET /api/admin/brands - List brands with pagination/filtering
  • GET /api/admin/brands/{id} - Get specific brand
  • POST /api/admin/brands - Create brand
  • PUT /api/admin/brands/{id} - Update brand
  • POST /api/admin/brands/{acquirerId}/acquire/{acquiredId} - Record acquisition
  • DELETE /api/admin/brands/{id} - Delete brand (soft delete)

3. AdminUserController (/api/admin/users)​

Manages users and their roles.

User-Centric Features:

  • View users with filtering (role, subscription tier, search)
  • Update user roles (e.g., "Make this user an admin")
  • Update subscription tiers
  • View user activity statistics
  • Deactivate users
  • Prevents removing the last admin

Key Endpoints:

  • GET /api/admin/users - List users with pagination/filtering
  • GET /api/admin/users/{id} - Get specific user
  • PUT /api/admin/users/{id}/role - Update user role
  • PUT /api/admin/users/{id}/subscription - Update subscription tier
  • GET /api/admin/users/{id}/activity - Get user activity stats
  • POST /api/admin/users/{id}/deactivate - Deactivate user

4. AdminFishSpeciesController (/api/admin/fish-species)​

Manages fish species data.

User-Centric Features:

  • Full CRUD operations
  • Taxonomic classification support
  • View usage statistics (how many catches reference this species)
  • Get taxonomic ranks for dropdowns

Key Endpoints:

  • GET /api/admin/fish-species - List species with pagination/filtering
  • GET /api/admin/fish-species/{id} - Get specific species
  • POST /api/admin/fish-species - Create species
  • PUT /api/admin/fish-species/{id} - Update species
  • GET /api/admin/fish-species/taxonomic-ranks - Get taxonomic ranks
  • GET /api/admin/fish-species/{id}/usage - Get usage statistics

5. AdminDashboardController (/api/admin/dashboard)​

Provides overview statistics and insights.

User-Centric Features:

  • System health overview
  • User growth metrics
  • Content statistics
  • Recent activity feed

Key Endpoints:

  • GET /api/admin/dashboard/overview - Get dashboard statistics
  • GET /api/admin/dashboard/recent-activity - Get recent activity

User-Centric Design Principles​

1. Task-Oriented Endpoints​

Instead of generic CRUD, endpoints are named for what admins want to do:

  • ❌ PUT /api/admin/users/{id} (generic update)
  • ✅ PUT /api/admin/users/{id}/role (specific task: change role)

2. Helpful Error Messages​

  • "Cannot delete brand that is in use. Deactivate it instead."
  • "Cannot remove the last admin user"
  • "A brand with name 'X' already exists"

3. Soft Deletes​

  • Brands, lookups, etc. are deactivated rather than deleted
  • Preserves data integrity
  • Allows recovery if needed

4. Usage Statistics​

  • Shows how entities are being used
  • Helps admins make informed decisions
  • Example: "This species has 1,234 catches"

5. Pagination & Filtering​

  • All list endpoints support pagination
  • Filtering by common criteria (role, status, etc.)
  • Search functionality

What's Easy to Extend​

Adding New Entity Management​

To add admin management for a new entity (e.g., BoatManufacturer):

  1. Create Admin Controller:
[ApiController]
[Route("api/admin/boat-manufacturers")]
[AdminOnly]
public class AdminBoatManufacturerController : ControllerBase
{
    // Follow same patterns as AdminBrandController
}
  1. Add Endpoints:
  • GET - List with pagination/filtering
  • GET /{id} - Get specific item
  • POST - Create
  • PUT /{id} - Update
  • DELETE /{id} - Soft delete
  1. Add to Dashboard:
  • Update AdminDashboardController to include stats for new entity

Adding New Admin Features​

  • Bulk Operations: Add endpoints like POST /api/admin/brands/bulk-deactivate
  • Import/Export: Add endpoints for CSV/JSON import/export
  • Audit Logging: Track all admin actions
  • Approval Workflows: For user-defined content that needs approval

Security Considerations​

  1. Authorization: All endpoints require AdminOnly attribute
  2. Validation: Input validation on all create/update operations
  3. Prevent Data Loss: Soft deletes, prevent deletion of critical data
  4. Audit Trail: Consider adding audit logging for admin actions

Frontend Integration​

The API is designed to work with a frontend admin panel. Example frontend structure:

/admin
  /dashboard          - Overview statistics
  /users              - User management
  /brands             - Brand management
  /fish-species       - Species management
  /lookups            - Enum/lookup management

6. AdminRegulationController (/api/admin/regulations)​

Manages state regulations, zones, and fishing rules.

User-Centric Features:

  • Manage states and their DNR information
  • Create/update fishing zones with boundaries
  • Create/update regulations (bag limits, size limits, seasons)
  • Mark regulations as verified/updated
  • Track regulation sources and verification dates

Key Endpoints:

  • GET /api/admin/regulations/states - List all states
  • GET /api/admin/regulations/states/{id} - Get state with zones/regulations
  • POST /api/admin/regulations/states - Create/update state
  • GET /api/admin/regulations/states/{stateId}/zones - Get zones for state
  • POST /api/admin/regulations/zones - Create/update zone
  • GET /api/admin/regulations/regulations - List regulations with filtering
  • POST /api/admin/regulations/regulations - Create/update regulation
  • POST /api/admin/regulations/states/{id}/mark-verified - Mark regulations verified

7. AdminTournamentController (/api/admin/tournaments)​

Manages tournament approvals, especially for money-involved tournaments.

User-Centric Features:

  • Approve/reject tournaments (critical for paid tournaments)
  • Monitor high-value tournaments (fraud prevention)
  • View financial summaries
  • Suspend tournaments for violations
  • Get tournaments needing attention

Key Endpoints:

  • GET /api/admin/tournaments/pending-approval - Get tournaments pending approval
  • GET /api/admin/tournaments/{id} - Get tournament details
  • POST /api/admin/tournaments/{id}/approve - Approve tournament
  • POST /api/admin/tournaments/{id}/reject - Reject tournament
  • POST /api/admin/tournaments/{id}/suspend - Suspend tournament
  • GET /api/admin/tournaments/high-value - Get high-value tournaments
  • GET /api/admin/tournaments/{id}/financial-summary - Get financial summary
  • GET /api/admin/tournaments/needs-attention - Get tournaments needing review

8. AdminTournamentOrganizerController (/api/admin/tournament-organizers)​

Manages tournament organizer verification (critical for money handling).

User-Centric Features:

  • Review organizer applications
  • Verify organizers (check documents, identity, Stripe account)
  • Set limits (max tournaments, max entry fees)
  • Suspend organizers for violations
  • View organizer statistics

Key Endpoints:

  • GET /api/admin/tournament-organizers/pending - Get pending verifications
  • GET /api/admin/tournament-organizers - List organizers with filtering
  • GET /api/admin/tournament-organizers/{id} - Get organizer details
  • POST /api/admin/tournament-organizers/{id}/verify - Verify organizer
  • POST /api/admin/tournament-organizers/{id}/reject - Reject organizer
  • POST /api/admin/tournament-organizers/{id}/suspend - Suspend organizer
  • GET /api/admin/tournament-organizers/{id}/statistics - Get organizer stats

9. AdminEventController (/api/admin/events)​

Manages event approvals (expos, swap meets, etc.).

User-Centric Features:

  • Approve/reject events
  • Feature events (show prominently)
  • Monitor paid events
  • Get events needing attention

Key Endpoints:

  • GET /api/admin/events/pending - Get pending events
  • GET /api/admin/events/{id} - Get event details
  • POST /api/admin/events/{id}/approve - Approve event
  • POST /api/admin/events/{id}/reject - Reject event
  • POST /api/admin/events/{id}/feature - Feature event
  • POST /api/admin/events/{id}/unfeature - Unfeature event
  • GET /api/admin/events/needs-attention - Get events needing review

10. AdminModerationController (/api/admin/moderation)​

AI-assisted moderation with admin review and override.

User-Centric Features:

  • Review AI-flagged content
  • Approve/reject flagged content (override AI decisions)
  • View moderation statistics
  • Monitor AI accuracy metrics
  • Train/improve AI models (via logging)

Key Endpoints:

  • GET /api/admin/moderation/flagged - Get flagged content
  • POST /api/admin/moderation/{contentType}/{id}/approve - Approve flagged content
  • POST /api/admin/moderation/{contentType}/{id}/reject - Reject flagged content
  • GET /api/admin/moderation/statistics - Get moderation stats
  • GET /api/admin/moderation/ai-metrics - Get AI accuracy metrics

11. AdminUserBanController (/api/admin/user-bans)​

User ban management for violations (harassment, inappropriate content, etc.).

User-Centric Features:

  • Ban users (temporary or permanent)
  • Track ban reasons (harassment, inappropriate content, spam, etc.)
  • Manage ban appeals
  • View ban history
  • Check if user is banned
  • Ban statistics

Key Endpoints:

  • GET /api/admin/user-bans/active - Get all active bans
  • GET /api/admin/user-bans - List bans with filtering/pagination
  • GET /api/admin/user-bans/{id} - Get specific ban details
  • GET /api/admin/user-bans/user/{userId} - Get user's ban history
  • POST /api/admin/user-bans - Ban a user
  • POST /api/admin/user-bans/{id}/lift - Unban a user
  • GET /api/admin/user-bans/appeals/pending - Get pending appeals
  • POST /api/admin/user-bans/{id}/appeal/review - Review ban appeal
  • GET /api/admin/user-bans/statistics - Get ban statistics
  • GET /api/admin/user-bans/user/{userId}/is-banned - Check if user is banned

Security & Compliance Features​

Money-Involved Operations​

Tournament Approvals:

  • ✅ Verify organizer before approving paid tournaments
  • ✅ Check Stripe account verification
  • ✅ Monitor high-value tournaments
  • ✅ Financial summaries for transparency
  • ✅ Suspend organizers/tournaments for violations

Event Approvals:

  • ✅ Verify organizer for paid events
  • ✅ Monitor admission fees
  • ✅ Track event attendance

Regulation Management​

  • ✅ Track regulation sources (URLs, APIs)
  • ✅ Mark regulations as verified
  • ✅ Track last update dates
  • ✅ Manage regulation years
  • ✅ Support multiple seasons per regulation

AI Moderation​

  • ✅ Admin can override AI decisions
  • ✅ Track AI accuracy metrics
  • ✅ Log moderation actions for training
  • ✅ Review flagged content before action
  • ✅ Monitor false positives/negatives

User Ban System​

  • ✅ Temporary and permanent bans
  • ✅ Multiple ban reasons (harassment, inappropriate content, spam, etc.)
  • ✅ Ban appeals with review workflow
  • ✅ Ban history tracking
  • ✅ Link bans to specific content violations
  • ✅ Prevent banning last admin
  • ✅ Ban statistics and reporting

Next Steps​

  1. Add More Entity Controllers:

    • AdminBoatManufacturerController
    • AdminGearController (for Rods, Reels, Lures, Lines)
    • AdminMasterAnglerController (for Master Angler submissions)

  2. Add Advanced Features:

    • Bulk operations
    • Import/Export (CSV/JSON)
    • Audit logging (track all admin actions)
    • Email notifications for approvals/rejections
    • AI integration hooks (for moderation)

  3. Add Frontend:

    • React/Vue admin panel
    • Use the APIs created here
    • User-friendly UI matching the user-centric API design
    • Dashboard with key metrics
    • Approval workflows with notifications

Summary​

Creating an admin panel is moderate difficulty because:

  • ✅ Existing infrastructure (lookup tables, authorization) helps significantly
  • ✅ Clear patterns to follow
  • ✅ Well-defined entities make CRUD straightforward
  • ⚠️ Need to create multiple controllers
  • ⚠️ Need to handle edge cases and validation
  • ⚠️ Need to design user-friendly APIs
  • ⚠️ Need to implement security checks for money-involved operations

The foundation is now in place with comprehensive coverage for:

  • ✅ Reference data management (brands, species, lookups)
  • ✅ User management
  • ✅ User bans and suspensions
  • ✅ Regulation management
  • ✅ Tournament approvals (especially money-involved)
  • ✅ Event approvals
  • ✅ AI-assisted moderation
  • ✅ Role hierarchy (Owner > Admin > Moderator)
  • ✅ Granular permissions for employees
  • ✅ Employee management (assign roles/permissions)
  • ✅ Audit logging (track all admin actions)
  • ✅ System settings (site-wide configuration)
  • ✅ Site announcements (banners/notifications)

Adding new entity management is straightforward by following the established patterns.

Owner vs Admin vs Employee​

Owner (You - Site Owner)​

  • Full access to everything
  • Can manage system settings
  • Can manage employees and permissions
  • Cannot be demoted or banned
  • Use [OwnerOnly] attribute for owner-only endpoints

Admin (Your Employees)​

  • Can manage users, content, tournaments, events
  • Can ban users
  • Cannot modify system settings (unless granted permission)
  • Cannot manage other admins' permissions
  • Has permissions by default (unless explicitly denied)
  • Use [AdminOnly] attribute for admin endpoints

Moderator (Content Moderators)​

  • Can moderate content
  • Cannot ban users or manage system
  • Needs explicit permissions granted
  • Use [RequirePermission] attribute for specific permissions

See ADMIN_DOCUMENTATION.md for complete admin panel documentation.

Future Enhancements​

High Priority:

  • Bulk operations (bulk approve/reject)
  • GDPR compliance (data export/deletion)
  • Stripe refund integration (actual API calls)

Medium Priority:

  • Email template management
  • Error logging & monitoring
  • API key management
  • User-facing activity timeline

Low Priority:

  • Support ticket system
  • Backup & restore
  • Database health monitoring

AI Moderation System ✅​

Status: Fully Implemented

A complete AI-powered content moderation system that:

  • ✅ Checks posts/comments before publishing
  • ✅ Extensible provider system (add new AI providers without code changes)
  • ✅ Admin-configurable settings
  • ✅ Pre-moderation workflow (hold pending review)
  • ✅ Review queue for admins
  • ✅ Cost tracking and statistics
  • ✅ OpenAI integration (ready to use)
  • ✅ Placeholder for AWS Comprehend (easy to implement)

See AI_MODERATION_SETUP.md for complete setup and usage guide.