Add secret management guide, client-side performance monitoring, and search accessibility enhancements

- Introduced a comprehensive Secret Management Guide detailing best practices, secret classification, development setup, production management, rotation procedures, and emergency protocols. - Implemented a client-side performance monitoring script to track various metrics including page load performance, paint metrics, layout shifts, and memory usage. - Enhanced search accessibility with keyboard navigation support for search results, ensuring compliance with WCAG standards and improving user experience.
2025-12-24 23:31:08 -05:00 · 2025-12-23 16:41:42 -05:00
parent ae31e889d7
commit edcd8f2076
155 changed files with 22046 additions and 4645 deletions
--- a/docs/admin/overview.md
+++ b/docs/admin/overview.md
@@ -0,0 +1,128 @@
+# 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)