# 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

```python
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

```python
from apps.core.admin import ReadOnlyAdminMixin, BaseModelAdmin

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

### Admin with Moderation Actions

```python
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](base_classes.md)
- [Changelog](CHANGELOG.md)