thrillwiki_django_no_react/docs/admin/overview.md

Admin Interface Overview

This document provides an overview of the Django admin interface architecture for ThrillWiki.

Architecture

The admin interface is built on a layered architecture:

┌─────────────────────────────────────────────────────┐
│                  App-Specific Admins                │
│  (ParkAdmin, RideAdmin, UserAdmin, etc.)            │
├─────────────────────────────────────────────────────┤
│                     Mixins                          │
│  (QueryOptimizationMixin, ExportActionMixin, etc.)  │
├─────────────────────────────────────────────────────┤
│                  BaseModelAdmin                     │
│  (Standard settings, base functionality)            │
├─────────────────────────────────────────────────────┤
│               django.contrib.admin                  │
└─────────────────────────────────────────────────────┘

Key Components

Base Classes (apps/core/admin/)

• BaseModelAdmin: Standard settings (pagination, display, ordering)
• Mixins: Reusable functionality (query optimization, export, permissions)

Admin Sites

• Default Admin Site: Full admin access at /admin/
• Moderation Admin Site: Dedicated moderation interface at /moderation/

Performance Targets

View Type	Query Target	Load Time
List View	< 15 queries	< 500ms
Change View	< 20 queries	< 500ms
Bulk Actions	< 2 seconds	per 100 records

Quick Reference

Adding a New Admin

from apps.core.admin import (
    BaseModelAdmin,
    QueryOptimizationMixin,
    ExportActionMixin,
)

class MyModelAdmin(
    QueryOptimizationMixin,
    ExportActionMixin,
    BaseModelAdmin,
):
    list_display = ['name', 'related_obj', 'status', 'created_at']
    list_select_related = ['related_obj']
    list_prefetch_related = ['many_to_many_field']

    export_fields = ['id', 'name', 'status']
    export_filename_prefix = 'my_model'

Read-Only Admin for Auto-Generated Data

from apps.core.admin import ReadOnlyAdminMixin, BaseModelAdmin

class RankingAdmin(ReadOnlyAdminMixin, BaseModelAdmin):
    list_display = ['ride', 'rank', 'calculated_at']

Admin with Moderation Actions

from apps.core.admin import ModerationMixin, BaseModelAdmin

class ReviewAdmin(ModerationMixin, BaseModelAdmin):
    moderation_status_field = 'status'

Files Structure

backend/
├── apps/
│   ├── core/
│   │   ├── admin/
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   └── mixins.py
│   │   └── admin.py
│   ├── parks/
│   │   └── admin.py
│   ├── rides/
│   │   └── admin.py
│   ├── accounts/
│   │   └── admin.py
│   └── moderation/
│       └── admin.py
└── shared/
    └── media/
        └── admin.py

docs/admin/
├── overview.md
├── base_classes.md
└── CHANGELOG.md

Best Practices

1. Always use BaseModelAdmin as the final parent class
2. List mixins before BaseModelAdmin in inheritance order
3. Define list_select_related for all ForeignKeys in list_display
4. Use prefetch_related for reverse relations and M2M fields
5. Add export_fields explicitly for control over exported data
6. Include descriptive help text in fieldset descriptions
7. Test query counts using Django Debug Toolbar

Related Documentation

• Base Classes and Mixins
• Changelog