Add standardized HTMX conventions, interaction patterns, and migration guide for ThrillWiki UX

backend/config/django/base.py

@@ -151,6 +151,8 @@ if TEMPLATES_ENABLED:
                     "django.contrib.messages.context_processors.messages",
                     "apps.moderation.context_processors.moderation_access",
                     "apps.core.context_processors.fsm_context",
+                    "apps.core.context_processors.breadcrumbs",
+                    "apps.core.context_processors.page_meta",
                 ]
             },
         }
@@ -170,6 +172,8 @@ else:
                     "django.contrib.messages.context_processors.messages",
                     "apps.moderation.context_processors.moderation_access",
                     "apps.core.context_processors.fsm_context",
+                    "apps.core.context_processors.breadcrumbs",
+                    "apps.core.context_processors.page_meta",
                 ]
             },
         }
@@ -337,6 +341,7 @@ REST_FRAMEWORK = {
     ],
     "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
     "PAGE_SIZE": 20,
+    "MAX_PAGE_SIZE": 100,
     "DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.AcceptHeaderVersioning",
     "DEFAULT_VERSION": "v1",
     "ALLOWED_VERSIONS": ["v1"],
@@ -355,18 +360,59 @@ REST_FRAMEWORK = {
         "rest_framework.filters.SearchFilter",
         "rest_framework.filters.OrderingFilter",
     ],
+    "DEFAULT_THROTTLE_CLASSES": [
+        "rest_framework.throttling.AnonRateThrottle",
+        "rest_framework.throttling.UserRateThrottle",
+    ],
+    "DEFAULT_THROTTLE_RATES": {
+        "anon": "60/minute",
+        "user": "1000/hour",
+    },
     "TEST_REQUEST_DEFAULT_FORMAT": "json",
     "NON_FIELD_ERRORS_KEY": "non_field_errors",
     "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
 }
 
 # CORS Settings for API
+# https://github.com/adamchainz/django-cors-headers
 
 CORS_ALLOW_CREDENTIALS = True
 CORS_ALLOW_ALL_ORIGINS = config(
     "CORS_ALLOW_ALL_ORIGINS", default=False, cast=bool
 )  # type: ignore[arg-type]
 
+# Allowed HTTP headers for CORS requests
+CORS_ALLOW_HEADERS = [
+    "accept",
+    "accept-encoding",
+    "authorization",
+    "content-type",
+    "dnt",
+    "origin",
+    "user-agent",
+    "x-csrftoken",
+    "x-requested-with",
+    "x-api-version",
+]
+
+# HTTP methods allowed for CORS requests
+CORS_ALLOW_METHODS = [
+    "DELETE",
+    "GET",
+    "OPTIONS",
+    "PATCH",
+    "POST",
+    "PUT",
+]
+
+# Expose rate limit headers to browsers
+CORS_EXPOSE_HEADERS = [
+    "X-RateLimit-Limit",
+    "X-RateLimit-Remaining",
+    "X-RateLimit-Reset",
+    "X-API-Version",
+]
+
 
 API_RATE_LIMIT_PER_MINUTE = config(
     "API_RATE_LIMIT_PER_MINUTE", default=60, cast=int
@@ -376,13 +422,43 @@ API_RATE_LIMIT_PER_HOUR = config(
 )  # type: ignore[arg-type]
 SPECTACULAR_SETTINGS = {
     "TITLE": "ThrillWiki API",
-    "DESCRIPTION": "Comprehensive theme park and ride information API",
+    "DESCRIPTION": """Comprehensive theme park and ride information API.
+
+## API Conventions
+
+### Response Format
+All successful responses include a `success: true` field with data nested under `data`.
+All error responses include an `error` object with `code` and `message` fields.
+
+### Pagination
+List endpoints support pagination with `page` and `page_size` parameters.
+Default page size is 20, maximum is 100.
+
+### Filtering
+Range filters use `{field}_min` and `{field}_max` naming convention.
+Search uses the `search` parameter.
+Ordering uses the `ordering` parameter (prefix with `-` for descending).
+
+### Field Naming
+All field names use snake_case convention (e.g., `image_url`, `created_at`).
+""",
     "VERSION": "1.0.0",
     "SERVE_INCLUDE_SCHEMA": False,
     "COMPONENT_SPLIT_REQUEST": True,
     "TAGS": [
         {"name": "Parks", "description": "Theme park operations"},
         {"name": "Rides", "description": "Ride information and management"},
+        {"name": "Park Media", "description": "Park photos and media management"},
+        {"name": "Ride Media", "description": "Ride photos and media management"},
+        {"name": "Authentication", "description": "User authentication and session management"},
+        {"name": "Social Authentication", "description": "Social provider login and account linking"},
+        {"name": "User Profile", "description": "User profile management"},
+        {"name": "User Settings", "description": "User preferences and settings"},
+        {"name": "User Notifications", "description": "User notification management"},
+        {"name": "User Content", "description": "User-generated content (top lists, reviews)"},
+        {"name": "User Management", "description": "Admin user management operations"},
+        {"name": "Self-Service Account Management", "description": "User account deletion and management"},
+        {"name": "Core", "description": "Core utility endpoints (search, suggestions)"},
         {
             "name": "Statistics",
             "description": "Statistical endpoints providing aggregated data and insights",