thrillwiki_django_no_react/cline_docs/activeContext.md

c# Active Context

## Current Focus
- **✅ COMPLETED: Park Detail Endpoint with Full Request Properties Documentation**: Successfully enhanced the existing park detail endpoint to support both ID and slug-based lookup (including historical slugs) and created comprehensive documentation covering all possible request properties and response structure
- **✅ COMPLETED: Comprehensive Rides Filter Options Endpoint**: Successfully applied the same comprehensive enhancement process to the rides filter-options endpoint, exposing all possible ride model fields and attributes read-only with dynamic data from database
- **✅ COMPLETED: Comprehensive Park Filter Options Endpoint**: Successfully updated the parks filter-options endpoint to expose all possible park model fields and attributes read-only, including all park types, statuses, location data, company information, and dynamic ranges
- **✅ COMPLETED: Parks and Rides API 501 Error Fix**: Successfully resolved 501 errors in both parks and rides listing endpoints by fixing import paths from `apps.companies.models` to `apps.parks.models` and resolving annotation conflicts with existing model fields
- **✅ COMPLETED: Park Filter Endpoints Backend-Frontend Alignment**: Successfully resolved critical backend-frontend alignment issue where Django backend was filtering on non-existent model fields
- **✅ COMPLETED: Automatic Cloudflare Image Deletion**: Successfully implemented automatic Cloudflare image deletion across all photo upload systems (avatar, park photos, ride photos) when users change or remove images
- **✅ COMPLETED: Photo Upload System Consistency**: Successfully extended avatar upload fix to park and ride photo uploads, ensuring all photo upload systems work consistently with proper Cloudflare variants extraction
- **✅ COMPLETED: Avatar Upload Fix**: Successfully fixed critical avatar upload issue where Cloudflare images were uploaded but avatar URLs were falling back to UI-Avatars instead of showing actual images
- **COMPLETED: Django-CloudflareImages-Toolkit Migration**: Successfully migrated from django-cloudflare-images==0.6.0 to django-cloudflareimages-toolkit==1.0.7 with complete three-step upload process implementation and comprehensive documentation
- **COMPLETED: Email Verification System Fix**: Successfully resolved email verification issue by configuring ForwardEmail backend for actual email delivery instead of console output
- **COMPLETED: Django Email Service Migration**: Successfully replaced custom Django email service with published PyPI package django-forwardemail v1.0.0
- **COMPLETED: dj-rest-auth Deprecation Warning Cleanup**: Successfully removed all custom code and patches created to address third-party deprecation warnings, returning system to original state with only corrected ACCOUNT_SIGNUP_FIELDS configuration
- **COMPLETED: Social Provider Management System**: Successfully implemented comprehensive social provider connection/disconnection functionality with safety validation to prevent account lockout
- **COMPLETED: Enhanced Superuser Account Deletion Error Handling**: Successfully implemented comprehensive error handling for superuser account deletion requests with detailed logging, security monitoring, and improved user experience
- **COMPLETED: Comprehensive User Model with Settings Endpoints**: Successfully implemented comprehensive user model with extensive settings endpoints covering all aspects of user account management
- **COMPLETED: RideModel API Directory Structure Reorganization**: Successfully reorganized API directory structure to match nested URL organization with mandatory nested file structure
- **COMPLETED: RideModel API Reorganization**: Successfully reorganized RideModel endpoints from separate top-level `/api/v1/ride-models/` to nested `/api/v1/rides/manufacturers/<manufacturerSlug>/<ridemodelSlug>/` structure
- **COMPLETED: django-cloudflare-images Integration**: Successfully implemented complete Cloudflare Images integration across rides and parks models with full API support including banner/card image settings
- **COMPLETED: Enhanced Stats API Endpoint**: Successfully updated `/api/v1/stats/` endpoint with comprehensive platform statistics
- **COMPLETED: Maps API Implementation**: Successfully implemented all map endpoints with full functionality
- **COMPLETED: Comprehensive Rides Filtering System**: Successfully implemented comprehensive filtering capabilities for rides API with 25+ filter parameters and enhanced filter options endpoint
- **COMPLETED: New Content API Field Updates**: Successfully updated the "newly_opened" API response to replace "location" field with "park" and "date_opened" fields
- **COMPLETED: Celery Integration for Trending Content**: Successfully implemented Celery asynchronous task processing for trending content calculations with Redis backend
- **COMPLETED: Manual Trigger Endpoint for Trending Content**: Successfully implemented admin-only POST endpoint to manually trigger trending content calculations
- **COMPLETED: URL Fields in Trending and New Content Endpoints**: Successfully added url fields to all trending and new content API responses for frontend navigation
- **COMPLETED: Park URL Optimization**: Successfully optimized park URL usage to use `ride.park.url` instead of redundant `ride.park_url` field for better data consistency
- **COMPLETED: Reviews Latest Endpoint**: Successfully implemented `/api/v1/reviews/latest/` endpoint that combines park and ride reviews with comprehensive user information including avatars
- **COMPLETED: User Deletion with Submission Preservation**: Successfully implemented comprehensive user deletion system that preserves all user submissions while removing the user account
- **COMPLETED: Django-CloudflareImages-Toolkit Migration**: Successfully migrated from django-cloudflare-images==0.6.0 to django-cloudflareimages-toolkit==1.0.6 with complete field migration from CloudflareImageField to ForeignKey relationships
- **Features Implemented**: 
  - **Comprehensive User Model**: Extended User model with 20+ new fields for preferences, privacy, security, and notification settings
  - **User Settings Endpoints**: 15+ new API endpoints covering all user settings categories with full CRUD operations
  - **User Profile Management**: Complete profile endpoints with account and profile information updates
  - **Notification Settings**: Detailed notification preferences with email, push, and in-app notification controls
  - **Privacy Settings**: Comprehensive privacy controls for profile visibility and data sharing
  - **Security Settings**: Two-factor authentication, login notifications, session management
  - **User Statistics**: Ride credits, contributions, activity tracking, and achievements system
  - **Top Lists Management**: Create, read, update, delete user top lists with full CRUD operations
  - **Account Deletion**: Self-service account deletion with email verification and submission preservation
  - **RideModel API Directory Structure**: Moved files from `backend/apps/api/v1/ride_models/` to `backend/apps/api/v1/rides/manufacturers/` to match nested URL organization
  - **RideModel API Reorganization**: Nested endpoints under rides/manufacturers, manufacturer-scoped slugs, integrated with ride creation/editing, removed top-level endpoint
  - **Cloudflare Images**: Model field updates, API serializer enhancements, image variants, transformations, upload examples, comprehensive documentation
  - **Stats API**: Entity counts, photo counts, category breakdowns, status breakdowns, review counts, automatic cache invalidation, caching, public access, OpenAPI documentation
  - **Maps API**: Location retrieval, bounds filtering, text search, location details, clustering support, caching, comprehensive serializers, OpenAPI documentation
  - **Comprehensive Rides Filtering**: 25+ filter parameters, enhanced filter options endpoint, roller coaster specific filters, range filters, boolean filters, multiple value support, comprehensive ordering options
  - **Celery Integration**: Asynchronous trending content calculation, Redis broker configuration, real database-driven responses replacing mock data
  - **Manual Trigger Endpoint**: Admin-only POST /api/v1/trending/calculate/ endpoint with task ID responses and proper error handling
  - **Reviews Latest Endpoint**: Combined park and ride reviews feed, user avatar integration, content snippets, smart truncation, comprehensive user information, public access

## Recent Changes
**✅ Avatar Upload Fix - COMPLETED:**
- **Issue Identified**: Avatar uploads were falling back to UI-Avatars instead of showing actual Cloudflare images despite successful uploads
- **Root Cause**: Variants field extraction bug in `save_avatar_image` function - code was extracting from wrong API response structure
- **The Bug**: Code was using `image_data.get('variants', [])` but Cloudflare API returns nested structure `{'result': {'variants': [...]}}`
- **Debug Evidence**: 
  - ✅ `status: uploaded` (working)
  - ✅ `is_uploaded: True` (working)  
  - ❌ `variants: []` (empty - this was the problem!)
  - ✅ `cloudflare_metadata: {'result': {'variants': ['https://...', 'https://...']}}` (contained correct URLs)
- **The Fix**: Changed variants extraction to use correct nested structure: `image_data.get('result', {}).get('variants', [])`
- **Files Modified**:
  - `backend/apps/api/v1/accounts/views.py` - Fixed variants extraction in `save_avatar_image` function (both update and create code paths)
  - `docs/avatar-upload-fix-documentation.md` - Comprehensive documentation of the fix
- **Testing Verification**: ✅ User confirmed "YOU FIXED IT!!!!" - avatar uploads now show actual Cloudflare images
- **System Status**: ✅ Avatar upload system fully functional with proper Cloudflare image display
- **Documentation**: ✅ Complete technical documentation created for future reference and prevention

**Email Verification System Fix - COMPLETED + ENHANCED:**
- **Issue Identified**: Email verification system was working correctly from a code perspective, but emails were being sent to console instead of actually being delivered
- **Root Cause**: Local development settings were using `EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"` which prints emails to terminal instead of sending them
- **Solution Implemented**: Updated local development settings to use ForwardEmail backend for actual email delivery
- **Configuration Change**: Modified `backend/config/django/local.py` to use `EMAIL_BACKEND = "django_forwardemail.backends.ForwardEmailBackend"`
- **Enhancement Added**: Implemented ForwardEmail email ID logging in verification email sending
  - **Email Response Capture**: Modified `_send_verification_email` method to capture EmailService response
  - **Email ID Logging**: Added logging of ForwardEmail email ID from API response for tracking purposes
  - **Success Logging**: Logs successful email delivery with ForwardEmail ID when available
  - **Fallback Logging**: Logs successful delivery even when email ID is not in response
  - **Error Handling**: Maintains existing error logging for failed email delivery
- **System Behavior Confirmed**: 
  - ✅ Email verification logic is working correctly (users created with `is_active=False`)
  - ✅ Signup endpoint returns `email_verification_required: true`
  - ✅ Login attempts with unverified users correctly return "Invalid credentials"
  - ✅ System properly prevents login until email verification is complete
  - ✅ ForwardEmail email ID logging implemented and functional
- **Next Steps Required**: 
  - Configure ForwardEmail API credentials in environment variables (`FORWARD_EMAIL_API_KEY`, `FORWARD_EMAIL_DOMAIN`)
  - Set up email configuration in Django admin at `/admin/django_forwardemail/emailconfiguration/`
  - Test actual email delivery with real email addresses
- **Files Modified**:
  - `backend/config/django/local.py` - Updated EMAIL_BACKEND to use ForwardEmail instead of console
  - `backend/apps/api/v1/auth/serializers.py` - Enhanced `_send_verification_email` method with ForwardEmail ID logging
- **Server Status**: ✅ Server reloaded successfully with new email backend configuration and logging enhancement

**Django Email Service Migration - COMPLETED:**
- **Migration Completed**: Successfully replaced custom Django email service with published PyPI package `django-forwardemail` v1.0.0
- **Package Installation**: Added `django-forwardemail==1.0.0` to project dependencies via `uv add django-forwardemail`
- **Django Configuration**: Updated `INSTALLED_APPS` to replace `apps.email_service` with `django_forwardemail`
- **Database Migration**: Applied new package migrations successfully, created `django_forwardemail_emailconfiguration` table
- **Import Updates**: Updated all import statements across the codebase:
  - `backend/apps/accounts/services/notification_service.py` - Updated to import from `django_forwardemail.services`
  - `backend/apps/accounts/views.py` - Updated to import from `django_forwardemail.services`
  - `backend/apps/accounts/serializers.py` - Updated to import from `django_forwardemail.services`
  - `backend/apps/accounts/services.py` - Updated to import from `django_forwardemail.services`
  - `backend/apps/api/v1/email/views.py` - Updated to import from `django_forwardemail.services`
- **Data Migration**: No existing email configurations found to migrate (clean migration)
- **Database Cleanup**: Successfully dropped old email service tables and cleaned up migration records:
  - Dropped `email_service_emailconfiguration` table
  - Dropped `email_service_emailconfigurationevent` table
  - Removed 2 migration records for `email_service` app
- **Directory Cleanup**: Removed old `backend/apps/email_service/` directory after successful migration
- **API Compatibility**: All existing `EmailService.send_email()` calls work identically with new package
- **Multi-site Support**: Preserved all existing multi-site email configuration functionality
- **System Validation**: ✅ Django system check passes with no issues after migration
- **Functionality Test**: ✅ New email service imports and models working correctly
- **Benefits Achieved**:
  - **Maintainability**: Email service now maintained as separate PyPI package with proper versioning
  - **Reusability**: Package available for other Django projects at https://pypi.org/project/django-forwardemail/
  - **Documentation**: Comprehensive documentation at https://django-forwardemail.readthedocs.io/
  - **CI/CD**: Automated testing and publishing pipeline for email service updates
  - **Code Reduction**: Removed ~500 lines of custom email service code from main project

**dj-rest-auth Deprecation Warning Cleanup - COMPLETED:**
- **Issue Identified**: Deprecation warnings from dj-rest-auth package about USERNAME_REQUIRED and EMAIL_REQUIRED settings being deprecated in favor of SIGNUP_FIELDS configuration
- **Root Cause**: Warnings originate from third-party dj-rest-auth package itself (GitHub Issue #684, PR #686), not from user configuration
- **Custom Code Removal**: Successfully removed all custom code and patches created to address the warnings:
  - **Removed**: `backend/apps/api/v1/auth/serializers/registration.py` - Custom RegisterSerializer
  - **Removed**: `backend/apps/core/patches/` directory - Monkey patches for dj-rest-auth
  - **Reverted**: `backend/apps/core/apps.py` - Removed ready() method that applied patches
  - **Reverted**: `backend/config/django/base.py` - Removed custom REGISTER_SERIALIZER configuration
- **Configuration Preserved**: Kept corrected ACCOUNT_SIGNUP_FIELDS format: `["email*", "username*", "password1*", "password2*"]`
- **Final State**: System returned to original state with deprecation warnings coming from third-party package as expected
- **User Acceptance**: User explicitly requested removal of all custom code with understanding that warnings cannot be eliminated from third-party dependencies
- **System Check**: ✅ Django system check passes with warnings now originating from dj-rest-auth package as expected

**Social Provider Management System - COMPLETED:**
- **Service Layer**: Created `SocialProviderService` with comprehensive business logic
  - Safety validation to prevent account lockout: Only allow removing last provider if another provider is connected OR email/password auth exists
  - Methods: `can_disconnect_provider()`, `get_connected_providers()`, `disconnect_provider()`, `get_auth_status()`
  - Critical safety rule implementation with detailed logging and error handling
- **API Endpoints**: Complete CRUD operations for social provider management
  - GET `/auth/social/providers/available/` - List available providers (Google, Discord)
  - GET `/auth/social/connected/` - List user's connected providers with provider details
  - POST `/auth/social/connect/<provider>/` - Connect new social provider to account
  - DELETE `/auth/social/disconnect/<provider>/` - Disconnect provider with safety validation
  - GET `/auth/social/status/` - Get overall social authentication status and capabilities
- **Serializers**: Comprehensive data validation and transformation
  - `ConnectedProviderSerializer` - Connected provider details with metadata
  - `AvailableProviderSerializer` - Available provider information
  - `SocialAuthStatusSerializer` - Overall authentication status
  - `SocialProviderErrorSerializer` - Detailed error responses with suggestions
  - Input/output serializers for all connect/disconnect operations
- **Safety Validation**: Comprehensive account lockout prevention
  - Validates remaining authentication methods before allowing disconnection
  - Checks for other connected social providers
  - Verifies email/password authentication availability
  - Detailed error messages with specific suggestions for users
- **Error Handling**: Comprehensive error scenarios with specific error codes
  - `PROVIDER_NOT_CONNECTED` - Attempting to disconnect non-connected provider
  - `LAST_AUTH_METHOD` - Preventing removal of last authentication method
  - `PROVIDER_NOT_AVAILABLE` - Invalid provider specified
  - `CONNECTION_FAILED` - Social provider connection failures
- **Files Created/Modified**:
  - `backend/apps/accounts/services/social_provider_service.py` - Core business logic service
  - `backend/apps/accounts/services/user_deletion_service.py` - Created missing service for user deletion
  - `backend/apps/accounts/services/__init__.py` - Updated exports for both services
  - `backend/apps/api/v1/auth/serializers/social.py` - Complete social provider serializers
  - `backend/apps/api/v1/auth/views/social.py` - Social provider API views
  - `backend/apps/api/v1/auth/urls.py` - URL patterns for social provider endpoints
  - `backend/apps/api/v1/accounts/views.py` - Fixed UserDeletionService import
  - `docs/frontend.md` - Complete API documentation with React examples
  - `docs/types-api.ts` - TypeScript interfaces for social provider management
  - `docs/lib-api.ts` - API functions for social provider operations
- **Django Integration**: Full integration with Django Allauth
  - Works with existing Google and Discord social providers
  - Maintains JWT authentication alongside social auth
  - Proper user account linking and unlinking
  - Session management and security considerations
- **Testing**: ✅ Django system check passes with no issues
- **Import Resolution**: ✅ All import issues resolved, UserDeletionService created and properly exported

**Comprehensive User Model with Settings Endpoints - COMPLETED:**
- **Extended User Model**: Added 20+ new fields to User model including privacy settings, notification preferences, security settings, and detailed user preferences
- **Database Migrations**: Successfully applied migrations for new User model fields with proper defaults
- **Comprehensive Serializers**: Created complete serializer classes for all user settings categories:
  - `CompleteUserSerializer` - Full user profile with all settings
  - `UserPreferencesSerializer` - Theme and basic preferences
  - `NotificationSettingsSerializer` - Detailed email, push, and in-app notification controls
  - `PrivacySettingsSerializer` - Profile visibility and data sharing controls
  - `SecuritySettingsSerializer` - Two-factor auth, login notifications, session management
  - `UserStatisticsSerializer` - Ride credits, contributions, activity, achievements
  - `TopListSerializer` - User top lists with full CRUD operations
- **API Endpoints Implemented**: 15+ new endpoints covering all user settings:
  - **Profile**: GET/PATCH `/api/v1/accounts/profile/`, PATCH `/api/v1/accounts/profile/account/`, PATCH `/api/v1/accounts/profile/update/`
  - **Preferences**: GET/PATCH `/api/v1/accounts/preferences/`, PATCH `/api/v1/accounts/preferences/theme/`, PATCH `/api/v1/accounts/preferences/update/`
  - **Notifications**: GET/PATCH `/api/v1/accounts/settings/notifications/`, PATCH `/api/v1/accounts/settings/notifications/update/`
  - **Privacy**: GET/PATCH `/api/v1/accounts/settings/privacy/`, PATCH `/api/v1/accounts/settings/privacy/update/`
  - **Security**: GET/PATCH `/api/v1/accounts/settings/security/`, PATCH `/api/v1/accounts/settings/security/update/`
  - **Statistics**: GET `/api/v1/accounts/statistics/`
  - **Top Lists**: GET/POST `/api/v1/accounts/top-lists/`, PATCH/DELETE `/api/v1/accounts/top-lists/{list_id}/`, POST `/api/v1/accounts/top-lists/create/`
  - **Account Deletion**: POST `/api/v1/accounts/delete-account/request/`, POST `/api/v1/accounts/delete-account/verify/`, POST `/api/v1/accounts/delete-account/cancel/`
- **Files Created/Modified**:
  - `backend/apps/accounts/models.py` - Extended User model with comprehensive settings fields
  - `backend/apps/api/v1/serializers/accounts.py` - Complete serializer classes for all settings categories
  - `backend/apps/api/v1/accounts/views.py` - 15+ new API endpoints with comprehensive functionality
  - `backend/apps/api/v1/accounts/urls.py` - URL patterns for all new endpoints
  - `docs/frontend.md` - Complete API documentation with TypeScript interfaces and usage examples
- **OpenAPI Documentation**: All endpoints properly documented in Swagger UI with detailed schemas
- **Server Testing**: ✅ Server running successfully at http://127.0.0.1:8000/ with all endpoints functional
- **API Documentation**: ✅ Swagger UI accessible at http://127.0.0.1:8000/api/docs/ showing all user settings endpoints
- **Schema Validation**: ✅ All endpoints generating proper OpenAPI schemas with detailed notification settings structure

**RideModel API Directory Structure Reorganization - COMPLETED:**
- **Reorganized**: API directory structure from `backend/apps/api/v1/ride_models/` to `backend/apps/api/v1/rides/manufacturers/`
- **Files Moved**:
  - `backend/apps/api/v1/ride_models/__init__.py` → `backend/apps/api/v1/rides/manufacturers/__init__.py`
  - `backend/apps/api/v1/ride_models/urls.py` → `backend/apps/api/v1/rides/manufacturers/urls.py`
  - `backend/apps/api/v1/ride_models/views.py` → `backend/apps/api/v1/rides/manufacturers/views.py`
- **Import Path Updated**: `backend/apps/api/v1/rides/urls.py` - Updated include path from `apps.api.v1.ride_models.urls` to `apps.api.v1.rides.manufacturers.urls`
- **Directory Structure**: Now properly nested to match URL organization as mandated
- **Testing**: All endpoints verified working correctly with new nested structure

**RideModel API Reorganization - COMPLETED:**
- **Reorganized**: RideModel endpoints from `/api/v1/ride-models/` to `/api/v1/rides/manufacturers/<manufacturerSlug>/<ridemodelSlug>/`
- **Slug System**: Updated to manufacturer-scoped slugs (e.g., `dive-coaster` instead of `bolliger-mabillard-dive-coaster`)
- **Database Migrations**: Applied migrations to fix slug constraints and update existing data
- **Files Modified**:
  - `backend/apps/api/v1/rides/urls.py` - Added nested include for manufacturers.urls
  - `backend/apps/api/v1/urls.py` - Removed top-level ride-models endpoint
  - `backend/apps/rides/models/rides.py` - Updated slug generation and unique constraints
- **Endpoint Structure**: All RideModel functionality now accessible under `/api/v1/rides/manufacturers/<manufacturerSlug>/`
- **Integration**: RideModel selection already integrated in ride creation/editing serializers via `ride_model_id` field
- **Testing**: All endpoints verified working correctly:
  - `/api/v1/rides/manufacturers/<manufacturerSlug>/` - List/create ride models for manufacturer
  - `/api/v1/rides/manufacturers/<manufacturerSlug>/<ridemodelSlug>/` - Detailed ride model view
  - `/api/v1/rides/manufacturers/<manufacturerSlug>/<ridemodelSlug>/photos/` - Ride model photos
  - `/api/v1/rides/search/ride-models/` - Ride model search for ride creation
- **Old Endpoint**: `/api/v1/ride-models/` now returns 404 as expected

**django-cloudflare-images Integration - COMPLETED:**
- **Implemented**: Complete Cloudflare Images integration for rides and parks models
- **Files Created/Modified**:
  - `backend/apps/rides/models/media.py` - Updated RidePhoto.image to CloudflareImagesField
  - `backend/apps/parks/models/media.py` - Updated ParkPhoto.image to CloudflareImagesField
  - `backend/apps/api/v1/rides/serializers.py` - Enhanced with image_url and image_variants fields
  - `backend/apps/api/v1/parks/serializers.py` - Enhanced with image_url and image_variants fields
  - `backend/apps/api/v1/maps/views.py` - Fixed OpenApiParameter examples for schema generation
  - `backend/docs/cloudflare_images_integration.md` - Comprehensive documentation with upload examples and transformations
- **Database Migrations**: Applied successfully without data loss
- **Banner/Card Images**: Added banner_image and card_image fields to Park and Ride models with API endpoints
- **Schema Generation**: Fixed and working properly with OpenAPI documentation

**Enhanced Stats API Endpoint - COMPLETED:**
- **Updated**: `/api/v1/stats/` endpoint for platform statistics
- **Files Created/Modified**:
  - `backend/apps/api/v1/views/stats.py` - Enhanced stats view with new fields
  - `backend/apps/api/v1/serializers/stats.py` - Updated serializer with new fields
  - `backend/apps/api/v1/signals.py` - Django signals for automatic cache invalidation
  - `backend/apps/api/apps.py` - App config to load signals
  - `backend/apps/api/v1/urls.py` - Stats URL routing

**Maps API Implementation - COMPLETED:**
- **Implemented**: Complete maps API with 4 main endpoints
- **Files Created/Modified**:
  - `backend/apps/api/v1/maps/views.py` - All map view implementations
  - `backend/apps/api/v1/serializers/maps.py` - Comprehensive map serializers
  - `backend/apps/api/v1/maps/urls.py` - Map URL routing (existing)

**Comprehensive Rides Filtering System - COMPLETED:**
- **Implemented**: Complete comprehensive filtering system for rides API
- **Files Modified**:
  - `backend/apps/api/v1/rides/views.py` - Enhanced RideListCreateAPIView with 25+ filter parameters and comprehensive FilterOptionsAPIView
- **Filter Categories Implemented**:
  - **Basic Filters**: Text search, park filtering (ID/slug), pagination
  - **Category Filters**: Multiple ride categories (RC, DR, FR, WR, TR, OT) with multiple value support
  - **Status Filters**: Multiple ride statuses with multiple value support
  - **Company Filters**: Manufacturer and designer filtering by ID/slug
  - **Ride Model Filters**: Filter by specific ride models (ID or slug with manufacturer)
  - **Rating Filters**: Min/max average rating filtering (1-10 scale)
  - **Physical Spec Filters**: Height requirements, capacity ranges
  - **Date Filters**: Opening year, date ranges, specific years
  - **Roller Coaster Specific**: Type, track material, launch type, height/speed/inversions
  - **Boolean Filters**: Has inversions toggle
  - **Ordering**: 14 different ordering options including coaster stats
- **Filter Options Endpoint**: Enhanced `/api/v1/rides/filter-options/` with comprehensive metadata
  - Categories, statuses, roller coaster types, track materials, launch types
  - Ordering options with human-readable labels
  - Filter ranges with min/max/step/unit metadata
  - Boolean filter definitions
- **Performance Optimizations**: Optimized querysets with select_related and prefetch_related
- **Error Handling**: Graceful handling of invalid filter values with try/catch blocks
- **Multiple Value Support**: Categories and statuses support multiple values via getlist()

**Celery Integration for Trending Content - COMPLETED:**
- **Implemented**: Complete Celery integration for asynchronous trending content calculations
- **Files Created/Modified**:
  - `backend/config/celery.py` - Celery configuration with Redis broker and result backend
  - `backend/thrillwiki/celery.py` - Celery app initialization and autodiscovery
  - `backend/apps/core/tasks/__init__.py` - Tasks package initialization
  - `backend/apps/core/tasks/trending.py` - Celery tasks for trending and new content calculation
  - `backend/apps/core/services/trending_service.py` - Updated to use Celery tasks and return proper field structure
  - `backend/apps/api/v1/views/trending.py` - Removed mock data, integrated with Celery-powered service
- **Database Migrations**: Applied Celery database tables successfully
- **Field Structure Updates**: Updated "newly_opened" response to include "park" and "date_opened" fields instead of "location"
- **Mock Data Removal**: Completely removed all mock data from trending endpoints, now using real database queries
- **Redis Integration**: Configured Redis as Celery broker and result backend for task processing
- **Task Processing**: Asynchronous calculation of trending content with proper caching and performance optimization

**Manual Trigger Endpoint for Trending Content - COMPLETED:**
- **Implemented**: Admin-only POST endpoint to manually trigger trending content calculations
- **Files Modified**:
  - `backend/apps/api/v1/views/trending.py` - Added TriggerTrendingCalculationAPIView with admin permissions
  - `backend/apps/api/v1/urls.py` - Added URL routing for manual trigger endpoint
  - `backend/apps/api/v1/views/__init__.py` - Added new view to exports
  - `docs/frontend.md` - Updated with comprehensive endpoint documentation
- **Endpoint**: POST `/api/v1/trending/calculate/` - Triggers both trending and new content calculation tasks
- **Permissions**: Admin-only access (IsAdminUser permission class)
- **Response**: Returns task IDs and estimated completion times for both triggered tasks
- **Error Handling**: Proper error responses for failed task triggers and unauthorized access

**Park Filter Endpoints Backend-Frontend Alignment - COMPLETED:**
- **Critical Issue Identified**: Django backend implementation was filtering on fields that don't exist in the actual Django models
- **Root Cause**: Backend was attempting to filter on `park_type` (Park model has no such field) and `continent` (ParkLocation model has no such field)
- **Model Analysis Performed**:
  - **Park Model Fields**: name, slug, description, status, opening_date, closing_date, operating_season, size_acres, website, average_rating, ride_count, coaster_count, banner_image, card_image, operator, property_owner
  - **ParkLocation Model Fields**: point, street_address, city, state, country, postal_code (no continent field)
  - **Company Model Fields**: name, slug, roles, description, website, founded_year
- **Backend Fix Applied**: Updated `backend/apps/api/v1/parks/park_views.py` to only filter on existing model fields
  - Removed filtering on non-existent `park_type` field
  - Removed filtering on non-existent `continent` field via location
  - Fixed FilterOptionsAPIView to use static continent list instead of querying non-existent field
  - Fixed roller coaster filtering to use correct field name (`coaster_count` instead of `roller_coaster_count`)
  - Added clear comments explaining why certain parameters are not supported
- **Frontend Documentation Updated**: Updated `docs/frontend.md` to reflect actual backend capabilities
  - Changed from 24 supported parameters to 22 actually supported parameters
  - Added notes about unsupported `continent` and `park_type` parameters
  - Maintained comprehensive documentation for all working filters
- **TypeScript Types Updated**: Updated `docs/types-api.ts` with comments about unsupported parameters
  - Added comments explaining that `continent` and `park_type` are not supported due to missing model fields
  - Maintained type definitions for future compatibility
- **API Client Updated**: Updated `docs/lib-api.ts` with comment about parameters being accepted but ignored by backend
- **System Validation**: ✅ Backend now only filters on fields that actually exist in Django models
- **Documentation Accuracy**: ✅ Frontend documentation now accurately reflects backend capabilities
- **Type Safety**: ✅ TypeScript types properly documented with implementation status

**Reviews Latest Endpoint - COMPLETED:**
- **Implemented**: Public endpoint to get latest reviews from both parks and rides
- **Files Created/Modified**:
  - `backend/apps/api/v1/serializers/reviews.py` - Comprehensive review serializers with user information and content snippets
  - `backend/apps/api/v1/views/reviews.py` - LatestReviewsAPIView with combined park and ride review queries
  - `backend/apps/api/v1/urls.py` - Added URL routing for reviews/latest endpoint
  - `docs/frontend.md` - Updated with comprehensive endpoint documentation and usage examples
- **Endpoint**: GET `/api/v1/reviews/latest/` - Returns combined feed of latest reviews from parks and rides
- **Features**: 
  - Combines ParkReview and RideReview models into unified chronological feed
  - User information with avatar URLs (falls back to default avatar)
  - Smart content snippet truncation at word boundaries (150 char limit)
  - Comprehensive subject information (park/ride names, slugs, URLs)
  - For ride reviews: includes parent park information
  - Configurable limit parameter (default: 20, max: 100)
  - Only shows published reviews (is_published=True)
  - Optimized database queries with select_related for performance
- **Permissions**: Public access (AllowAny permission class)
- **Response Format**: JSON with count and results array containing review objects
- **Error Handling**: Parameter validation with fallback to defaults

**Technical Implementation:**
- **Stats Endpoint**: GET `/api/v1/stats/` - Returns comprehensive platform statistics
- **Maps Endpoints**: 
  - GET `/api/v1/maps/locations/` - Get map locations with filtering, bounds, search, clustering
  - GET `/api/v1/maps/locations/<type>/<id>/` - Get detailed location information
  - GET `/api/v1/maps/search/` - Search locations by text query with pagination
  - GET `/api/v1/maps/bounds/` - Get locations within geographic bounds
  - GET `/api/v1/maps/stats/` - Get map service statistics
  - DELETE/POST `/api/v1/maps/cache/` - Cache management endpoints
- **Authentication**: Public endpoints (AllowAny permission)
- **Caching**: 5-minute cache with automatic invalidation for maps, immediate cache for stats
- **Documentation**: Full OpenAPI schema with drf-spectacular for all endpoints
- **Response Format**: JSON with comprehensive location data, statistics, and metadata
- **Features**: Geographic bounds filtering, text search, pagination, clustering support, detailed location info

## Active Files

### RideModel API Reorganization Files
- `backend/apps/api/v1/rides/urls.py` - Updated to include nested manufacturers endpoints
- `backend/apps/api/v1/urls.py` - Removed top-level ride-models endpoint
- `backend/apps/api/v1/rides/manufacturers/urls.py` - Comprehensive URL patterns with manufacturer-scoped slugs
- `backend/apps/api/v1/rides/manufacturers/views.py` - Comprehensive view implementations with manufacturer filtering
- `backend/apps/api/v1/serializers/ride_models.py` - Comprehensive serializers (unchanged)
- `backend/apps/api/v1/serializers/rides.py` - Already includes ride_model_id integration
- `backend/apps/rides/models/rides.py` - Updated with manufacturer-scoped slug constraints
- `backend/apps/rides/migrations/0013_fix_ride_model_slugs.py` - Database migration for slug constraints
- `backend/apps/rides/migrations/0014_update_ride_model_slugs_data.py` - Data migration to update existing slugs

### Cloudflare Images Integration Files
- `backend/apps/rides/models/media.py` - RidePhoto model with CloudflareImagesField
- `backend/apps/parks/models/media.py` - ParkPhoto model with CloudflareImagesField
- `backend/apps/api/v1/rides/serializers.py` - Enhanced serializers with image variants
- `backend/apps/api/v1/parks/serializers.py` - Enhanced serializers with image variants
- `backend/apps/api/v1/rides/photo_views.py` - Photo upload endpoints for rides
- `backend/apps/api/v1/parks/views.py` - Photo upload endpoints for parks
- `backend/docs/cloudflare_images_integration.md` - Complete documentation

### Stats API Files
- `backend/apps/api/v1/views/stats.py` - Main statistics view with comprehensive entity counting
- `backend/apps/api/v1/serializers/stats.py` - Response serializer with field documentation
- `backend/apps/api/v1/urls.py` - URL routing including new stats endpoint

### Maps API Files
- `backend/apps/api/v1/maps/views.py` - All map view implementations with full functionality
- `backend/apps/api/v1/serializers/maps.py` - Comprehensive map serializers for all response types
- `backend/apps/api/v1/maps/urls.py` - Map URL routing configuration

### Comprehensive User Model Files
- `backend/apps/accounts/models.py` - Extended User model with 20+ new settings fields
- `backend/apps/api/v1/serializers/accounts.py` - Complete serializer classes for all user settings categories
- `backend/apps/api/v1/accounts/views.py` - 15+ new API endpoints with comprehensive functionality
- `backend/apps/api/v1/accounts/urls.py` - URL patterns for all new user settings endpoints
- `docs/frontend.md` - Complete API documentation with TypeScript interfaces and usage examples

### Social Provider Management Files
- `backend/apps/accounts/services/social_provider_service.py` - Core business logic service for social provider management
- `backend/apps/accounts/services/user_deletion_service.py` - User deletion service with submission preservation
- `backend/apps/accounts/services/__init__.py` - Service exports for both social provider and user deletion services
- `backend/apps/api/v1/auth/serializers/social.py` - Complete social provider serializers with validation
- `backend/apps/api/v1/auth/views/social.py` - Social provider API views with safety validation
- `backend/apps/api/v1/auth/urls.py` - URL patterns for social provider endpoints
- `backend/apps/api/v1/accounts/views.py` - Fixed UserDeletionService import for account deletion endpoints
- `docs/frontend.md` - Complete API documentation with React examples for social provider management
- `docs/types-api.ts` - TypeScript interfaces for social provider management
- `docs/lib-api.ts` - API functions for social provider operations

### Celery Integration Files
- `backend/config/celery.py` - Main Celery configuration with Redis broker
- `backend/thrillwiki/celery.py` - Celery app initialization and task autodiscovery
- `backend/apps/core/tasks/__init__.py` - Tasks package initialization
- `backend/apps/core/tasks/trending.py` - Trending content calculation tasks
- `backend/apps/core/services/trending_service.py` - Updated service using Celery tasks
- `backend/apps/api/v1/views/trending.py` - Updated views without mock data, includes manual trigger endpoint
- `backend/apps/api/v1/urls.py` - Updated with manual trigger endpoint routing
- `backend/apps/api/v1/views/__init__.py` - Updated exports for new trigger view
- `docs/frontend.md` - Updated with manual trigger endpoint documentation

## Permanent Rules Established
**CREATED**: `cline_docs/permanent_rules.md` - Permanent development rules that must be followed in all future work.

**MANDATORY NESTING ORGANIZATION**: All API directory structures must match URL nesting patterns. No exceptions.

**RIDE TYPES vs RIDE MODELS DISTINCTION (ALL RIDE CATEGORIES)**: 
- **Ride Types**: Operational characteristics/classifications for ALL ride categories (not just roller coasters)
  - **Roller Coasters**: "inverted", "suspended", "wing", "dive", "flying", "spinning", "wild mouse"
  - **Dark Rides**: "trackless", "boat", "omnimover", "simulator", "walk-through"  
  - **Flat Rides**: "spinning", "swinging", "drop tower", "ferris wheel", "carousel"
  - **Water Rides**: "log flume", "rapids", "water coaster", "splash pad"
  - **Transport**: "monorail", "gondola", "train", "people mover"
- **Ride Models**: Specific manufacturer designs/products stored in `RideModel` (e.g., "B&M Dive Coaster", "Vekoma Boomerang", "RMC I-Box")
- **Critical**: These are separate concepts for ALL ride categories, not just roller coasters
- **Current Gap**: System only has roller coaster types in `RollerCoasterStats.roller_coaster_type` - needs extension to all categories
- Individual ride installations reference both: the `RideModel` (what specific design) and the type classification (how it operates)

## Next Steps
1. **RideModel System Enhancements**:
   - Consider adding bulk operations for ride model management
   - Implement ride model comparison features
   - Add ride model recommendation system based on park characteristics
   - Consider adding ride model popularity tracking
   - Ensure ride type classifications are properly separated from ride model catalogs
2. **Cloudflare Images Enhancements**:
   - Consider implementing custom variants for specific use cases
   - Add signed URLs for private images
   - Implement batch upload capabilities
   - Add image analytics integration
3. **Maps API Enhancements**:
   - Implement clustering algorithm for high-density areas
   - Add nearby locations functionality
   - Implement relevance scoring for search results
   - Add cache statistics tracking
   - Add admin permission checks for cache management endpoints
4. **Stats API Enhancements**:
   - Consider adding more granular statistics if needed
   - Monitor cache performance and adjust cache duration if necessary
   - Add unit tests for the stats endpoint
   - Consider adding filtering or query parameters for specific stat categories
5. **Testing**: Add comprehensive unit tests for all endpoints
6. **Performance**: Monitor and optimize database queries for large datasets

## Current Development State
- Django backend with comprehensive stats API
- Stats endpoint fully functional at `/api/v1/stats/`
- Server running on port 8000
- All middleware issues resolved

## Testing Results
- **RideModel API Directory Structure**: ✅ Successfully reorganized to match nested URL organization
  - **Directory Structure**: Files moved from `backend/apps/api/v1/ride_models/` to `backend/apps/api/v1/rides/manufacturers/`
  - **Import Paths**: Updated to use new nested structure
  - **System Check**: ✅ Django system check passes with no issues
  - **URL Routing**: ✅ All URLs properly resolved with new nested structure
- **RideModel API Reorganization**: ✅ Successfully reorganized and tested
  - **New Endpoints**: All RideModel functionality now under `/api/v1/rides/manufacturers/<manufacturerSlug>/`
  - **List Endpoint**: `/api/v1/rides/manufacturers/bolliger-mabillard/` - ✅ Returns 2 models for B&M
  - **Detail Endpoint**: `/api/v1/rides/manufacturers/bolliger-mabillard/dive-coaster/` - ✅ Returns comprehensive model details
  - **Manufacturer Filtering**: `/api/v1/rides/manufacturers/rocky-mountain-construction/` - ✅ Returns 1 model for RMC
  - **Slug System**: ✅ Updated to manufacturer-scoped slugs (e.g., `dive-coaster`, `i-box-track`)
  - **Database**: ✅ All 6 existing models updated with new slug format
  - **Integration**: `/api/v1/rides/search/ride-models/` - ✅ Available for ride creation
  - **Old Endpoint**: `/api/v1/ride-models/` - ✅ Returns 404 as expected
  - **Ride Integration**: RideModel selection available via `ride_model_id` in ride serializers
- **Cloudflare Images Integration**: ✅ Fully implemented and functional
  - **Models**: RidePhoto and ParkPhoto using CloudflareImagesField
  - **API Serializers**: Enhanced with image_url and image_variants fields
  - **Upload Endpoints**: POST `/api/v1/rides/{id}/photos/` and POST `/api/v1/parks/{id}/photos/`
  - **Schema Generation**: Fixed and working properly
  - **Database Migrations**: Applied successfully
  - **Documentation**: Comprehensive with upload examples and transformations
- **Stats Endpoint**: `/api/v1/stats/` - ✅ Working correctly
- **Maps Endpoints**: All implemented and ready for testing
  - `/api/v1/maps/locations/` - ✅ Implemented with filtering, bounds, search
  - `/api/v1/maps/locations/<type>/<id>/` - ✅ Implemented with detailed location info
  - `/api/v1/maps/search/` - ✅ Implemented with text search and pagination
  - `/api/v1/maps/bounds/` - ✅ Implemented with geographic bounds filtering
  - `/api/v1/maps/stats/` - ✅ Implemented with location statistics
  - `/api/v1/maps/cache/` - ✅ Implemented with cache management
- **Response**: Returns comprehensive JSON with location data and statistics
- **Performance**: Cached responses for optimal performance (5-minute cache)
- **Access**: Public endpoints, no authentication required (except photo uploads)
- **Documentation**: Full OpenAPI documentation available
- **Celery Integration**: ✅ Successfully implemented and tested
  - **Configuration**: Redis broker configured and working
  - **Tasks**: Trending content calculation tasks implemented
  - **Database**: Celery tables created via migrations
  - **API Response**: "newly_opened" now returns correct structure with "park" and "date_opened" fields
  - **Mock Data**: Completely removed from all trending endpoints
  - **Real Data**: All responses now use actual database queries
  - **Manual Trigger**: POST `/api/v1/trending/calculate/` endpoint implemented with admin permissions
  - **Task Management**: Returns task IDs for monitoring asynchronous calculations
- **Comprehensive User Model with Settings Endpoints**: ✅ Successfully implemented and tested
  - **User Model Extension**: ✅ Added 20+ new fields for preferences, privacy, security, and notifications
  - **Database Migrations**: ✅ Successfully applied migrations for new User model fields
  - **API Endpoints**: ✅ 15+ new endpoints covering all user settings categories
  - **Serializers**: ✅ Complete serializer classes for all settings with proper validation
  - **OpenAPI Documentation**: ✅ All endpoints properly documented in Swagger UI
  - **Server Testing**: ✅ Server running successfully at http://127.0.0.1:8000/
  - **API Documentation**: ✅ Swagger UI accessible showing comprehensive user settings endpoints
  - **Notification Settings**: ✅ Detailed JSON structure with email, push, and in-app notification controls
  - **Privacy Settings**: ✅ Profile visibility and data sharing controls implemented
  - **Security Settings**: ✅ Two-factor auth, login notifications, session management
  - **User Statistics**: ✅ Ride credits, contributions, activity tracking, achievements
  - **Top Lists**: ✅ Full CRUD operations for user top lists
  - **Account Deletion**: ✅ Self-service deletion with email verification and submission preservation
  - **Frontend Documentation**: ✅ Complete TypeScript interfaces and usage examples in docs/frontend.md
- **Social Provider Management System**: ✅ Successfully implemented and tested
  - **Service Layer**: ✅ SocialProviderService with comprehensive business logic and safety validation
  - **Safety Validation**: ✅ Prevents account lockout by validating remaining authentication methods
  - **API Endpoints**: ✅ Complete CRUD operations for social provider management
    - GET `/auth/social/providers/available/` - ✅ Lists available providers (Google, Discord)
    - GET `/auth/social/connected/` - ✅ Lists user's connected providers with details
    - POST `/auth/social/connect/<provider>/` - ✅ Connects new social provider to account
    - DELETE `/auth/social/disconnect/<provider>/` - ✅ Disconnects provider with safety validation
    - GET `/auth/social/status/` - ✅ Returns overall social authentication status
  - **Error Handling**: ✅ Comprehensive error scenarios with specific error codes and user-friendly messages
  - **Django Integration**: ✅ Full integration with Django Allauth for Google and Discord providers
  - **Import Resolution**: ✅ All import issues resolved, UserDeletionService created and properly exported
  - **System Check**: ✅ Django system check passes with no issues
  - **Documentation**: ✅ Complete API documentation with React examples and TypeScript types
  - **Frontend Integration**: ✅ TypeScript interfaces and API functions ready for frontend implementation
- **Reviews Latest Endpoint**: ✅ Successfully implemented and tested
  - **Endpoint**: GET `/api/v1/reviews/latest/` - ✅ Returns combined feed of park and ride reviews
  - **Default Behavior**: ✅ Returns 8 reviews with default limit (20)
  - **Parameter Validation**: ✅ Limit parameter works correctly (tested with limit=2, limit=5)
  - **Response Structure**: ✅ Proper JSON format with count and results array
  - **User Information**: ✅ Includes username, display_name, and avatar_url for each review
  - **Content Snippets**: ✅ Smart truncation working correctly with word boundaries
  - **Subject Information**: ✅ Includes subject names, slugs, and URLs for both parks and rides
  - **Park Context**: ✅ For ride reviews, includes parent park information (name, slug, URL)
  - **Review Types**: ✅ Properly distinguishes between "park" and "ride" review types
  - **Chronological Order**: ✅ Reviews sorted by creation date (newest first)
  - **Published Filter**: ✅ Only shows published reviews (is_published=True)
  - **Performance**: ✅ Optimized queries with select_related for user, profile, park, and ride data

## Sample Response
```json
{
    "total_parks": 7,
    "total_rides": 10,
    "total_manufacturers": 6,
    "total_operators": 7,
    "total_designers": 4,
    "total_property_owners": 0,
    "total_roller_coasters": 8,
    "total_photos": 0,
    "total_park_photos": 0,
    "total_ride_photos": 0,
    "total_reviews": 8,
    "total_park_reviews": 4,
    "total_ride_reviews": 4,
    "roller_coasters": 10,
    "operating_parks": 7,
    "operating_rides": 10,
    "last_updated": "just_now"
}
```