# ThrillWiki Backend Django application powering ThrillWiki - a comprehensive theme park and roller coaster information system. ## Architecture ThrillWiki is a **Django monolith with HTMX-driven templates**, providing: - **Server-side rendering** with Django templates - **HTMX** for dynamic partial updates without full page reloads - **REST API** for programmatic access (mobile apps, integrations) - **Alpine.js** for minimal client-side state (form validation, UI toggles) ``` backend/ ├── apps/ # Django applications │ ├── accounts/ # User authentication and profiles │ ├── api/v1/ # REST API endpoints │ ├── core/ # Shared utilities, managers, services │ ├── location/ # Geographic data and services │ ├── media/ # Cloudflare Images integration │ ├── moderation/ # Content moderation workflows │ ├── parks/ # Theme park models and views │ └── rides/ # Ride information and statistics ├── config/ # Django configuration │ ├── django/ # Environment-specific settings │ │ ├── base.py # Core settings │ │ ├── local.py # Development overrides │ │ ├── production.py # Production overrides │ │ └── test.py # Test overrides │ └── settings/ # Modular settings modules │ ├── cache.py # Redis caching │ ├── database.py # Database and GeoDjango │ ├── email.py # Email configuration │ ├── logging.py # Logging setup │ ├── rest_framework.py # DRF, JWT, CORS │ ├── security.py # Security headers │ └── storage.py # Static/media files ├── templates/ # Django templates with HTMX │ ├── components/ # Reusable UI components │ ├── htmx/ # HTMX partial templates │ └── layouts/ # Base layout templates ├── static/ # Static assets └── tests/ # Test files ``` ## Technology Stack | Technology | Version | Purpose | |------------|---------|---------| | **Django** | 5.2.8+ | Web framework (security patched) | | **Django REST Framework** | 3.15.2+ | API framework (security patched) | | **HTMX** | 1.20.0+ | Dynamic UI updates | | **Alpine.js** | 3.x | Minimal client-side state | | **Tailwind CSS** | 3.x | Utility-first styling | | **PostgreSQL/PostGIS** | 14+ | Database with geospatial support | | **Redis** | 6+ | Caching and sessions | | **Celery** | 5.5+ | Background task processing | | **UV** | Latest | Python package management | ## Quick Start ### Prerequisites - Python 3.13+ - [uv](https://docs.astral.sh/uv/) package manager - PostgreSQL 14+ with PostGIS extension - Redis 6+ ### Setup 1. **Install dependencies** ```bash cd backend uv sync --frozen # Use locked versions for reproducibility # Or: uv sync # Allow updates within version constraints ``` 2. **Environment configuration** ```bash cp .env.example .env # Edit .env with your settings ``` 3. **Database setup** ```bash uv run manage.py migrate uv run manage.py createsuperuser ``` 4. **Start development server** ```bash uv run manage.py runserver ``` The application will be available at `http://localhost:8000`. ## HTMX Patterns ThrillWiki uses HTMX for server-driven interactivity. Key patterns: ### Partial Templates Views render partial templates for HTMX requests: ```python # In views.py def park_list(request): parks = Park.objects.optimized_for_list() template = "parks/partials/park_list.html" if request.htmx else "parks/park_list.html" return render(request, template, {"parks": parks}) ``` ### HX-Trigger Events Cross-component communication via custom events: ```html
``` ### Loading Indicators Skeleton loaders for better UX: ```html
{% include "components/skeleton_loader.html" %}
``` ### Field-Level Validation Real-time form validation: ```html ``` See [HTMX Patterns](../docs/htmx-patterns.md) for complete documentation. ## Hybrid API/HTML Endpoints Many views serve dual purposes through content negotiation: ```python class ParkDetailView(HybridViewMixin, DetailView): """ Returns HTML for browser requests, JSON for API requests. Browser: GET /parks/cedar-point/ -> HTML template API: GET /api/v1/parks/cedar-point/ -> JSON response """ model = Park template_name = "parks/park_detail.html" serializer_class = ParkSerializer ``` This approach: - Reduces code duplication - Ensures API and web views stay in sync - Supports both HTMX partials and JSON responses ## Configuration ### Settings Architecture ThrillWiki uses modular settings for maintainability: ``` config/ ├── django/ # Environment-specific settings │ ├── base.py # Core settings (imports modular settings) │ ├── local.py # Development overrides │ ├── production.py # Production overrides │ └── test.py # Test overrides ├── settings/ # Modular settings │ ├── cache.py # Redis caching │ ├── database.py # Database and GeoDjango │ ├── email.py # Email configuration │ ├── logging.py # Logging setup │ ├── rest_framework.py # DRF, JWT, CORS │ ├── secrets.py # Secret management │ ├── security.py # Security headers │ ├── storage.py # Static/media files │ ├── third_party.py # Allauth, Celery, etc. │ └── validation.py # Settings validation └── celery.py # Celery configuration ``` Validate configuration with: ```bash uv run manage.py validate_settings ``` ### Environment Variables Key environment variables: | Variable | Description | Required | |----------|-------------|----------| | `SECRET_KEY` | Django secret key | Yes | | `DEBUG` | Debug mode (True/False) | Yes | | `DATABASE_URL` | PostgreSQL connection URL | Yes | | `REDIS_URL` | Redis connection URL | Production | | `DJANGO_SETTINGS_MODULE` | Settings module to use | Yes | See [Environment Variables](../docs/configuration/environment-variables.md) for complete reference. ## Apps Overview ### Core Apps | App | Description | |-----|-------------| | **accounts** | User authentication, profiles, social auth (Google, Discord) | | **parks** | Theme park models, views, and operations | | **rides** | Ride models, coaster statistics, ride history | | **core** | Shared utilities, managers, services, middleware | ### Support Apps | App | Description | |-----|-------------| | **api/v1** | REST API endpoints with OpenAPI documentation | | **moderation** | Content moderation workflows and queue | | **location** | Geographic data, geocoding, map services | | **media** | Cloudflare Images integration | ## API Endpoints Base URL: `http://localhost:8000/api/v1/` ### Interactive Documentation - **Swagger UI**: `/api/docs/` - **ReDoc**: `/api/redoc/` - **OpenAPI Schema**: `/api/schema/` ### Core Endpoints | Endpoint | Description | |----------|-------------| | `/api/v1/auth/` | Authentication (login, signup, social auth) | | `/api/v1/parks/` | Theme park CRUD and filtering | | `/api/v1/rides/` | Ride CRUD and filtering | | `/api/v1/accounts/` | User profile and settings | | `/api/v1/maps/` | Map data and location services | | `/api/v1/health/` | Health check endpoints | See [API Documentation](../docs/THRILLWIKI_API_DOCUMENTATION.md) for complete reference. ## Testing ```bash # Run all tests uv run manage.py test # Run specific app tests uv run manage.py test apps.parks uv run manage.py test apps.rides # Run with coverage uv run coverage run manage.py test uv run coverage report # Run accessibility tests uv run manage.py test backend.tests.accessibility ``` ## Management Commands ThrillWiki provides numerous management commands for development, deployment, and maintenance. ### Configuration & Validation ```bash # Validate all settings and environment variables uv run manage.py validate_settings uv run manage.py validate_settings --strict # Treat warnings as errors uv run manage.py validate_settings --json # JSON output uv run manage.py validate_settings --secrets-only # Only validate secrets # Validate state machine configurations uv run manage.py validate_state_machines # List all FSM transition callbacks uv run manage.py list_transition_callbacks ``` ### Database Operations ```bash # Standard Django commands uv run manage.py migrate uv run manage.py makemigrations uv run manage.py showmigrations uv run manage.py createsuperuser # Fix migration history issues uv run manage.py fix_migrations uv run manage.py fix_migration_history # Reset database (DESTRUCTIVE - development only) uv run manage.py reset_db ``` ### Cache Management ```bash # Warm cache with frequently accessed data uv run manage.py warm_cache uv run manage.py warm_cache --parks-only uv run manage.py warm_cache --rides-only uv run manage.py warm_cache --metadata-only uv run manage.py warm_cache --dry-run # Preview without caching # Clear all caches uv run manage.py clear_cache ``` ### Data Management ```bash # Seed initial data (operators, manufacturers, etc.) uv run manage.py seed_initial_data # Create sample data for development uv run manage.py create_sample_data uv run manage.py create_sample_data --minimal # Quick setup uv run manage.py create_sample_data --clear # Clear existing first # Seed sample parks and rides uv run manage.py seed_sample_data # Seed test submissions for moderation uv run manage.py seed_submissions # Seed API test data uv run manage.py seed_data # Update park statistics (ride counts, ratings) uv run manage.py update_park_counts # Update ride rankings uv run manage.py update_ride_rankings ``` ### User & Authentication ```bash # Create test users uv run manage.py create_test_users # Delete user and all related data uv run manage.py delete_user # Setup user groups and permissions uv run manage.py setup_groups # Setup Django sites framework uv run manage.py setup_site # Social authentication setup uv run manage.py setup_social_auth uv run manage.py setup_social_providers uv run manage.py create_social_apps uv run manage.py check_social_apps uv run manage.py fix_social_apps uv run manage.py reset_social_apps uv run manage.py reset_social_auth uv run manage.py cleanup_social_auth uv run manage.py update_social_apps_sites uv run manage.py verify_discord_settings uv run manage.py test_discord_auth uv run manage.py check_all_social_tables uv run manage.py setup_social_auth_admin # Avatar management uv run manage.py generate_letter_avatars uv run manage.py regenerate_avatars ``` ### Content & Media ```bash # Static file management uv run manage.py collectstatic uv run manage.py optimize_static # Minify and compress # Media file management (in shared/media/) uv run manage.py download_photos uv run manage.py move_photos uv run manage.py fix_photo_paths ``` ### Trending & Discovery ```bash # Calculate trending content uv run manage.py calculate_trending uv run manage.py update_trending uv run manage.py test_trending # Calculate new content for discovery uv run manage.py calculate_new_content ``` ### Testing & Development ```bash # Run development server with auto-reload uv run manage.py rundev # Setup development environment uv run manage.py setup_dev # Test location services uv run manage.py test_location # Test FSM transition callbacks uv run manage.py test_transition_callbacks # Analyze FSM transitions uv run manage.py analyze_transitions # Cleanup test data uv run manage.py cleanup_test_data ``` ### Security & Auditing ```bash # Run security audit uv run manage.py security_audit ``` ### Command Categories | Category | Commands | |----------|----------| | **Configuration** | validate_settings, validate_state_machines, list_transition_callbacks | | **Database** | migrate, makemigrations, reset_db, fix_migrations | | **Cache** | warm_cache, clear_cache | | **Data** | seed_initial_data, create_sample_data, update_park_counts, update_ride_rankings | | **Users** | create_test_users, delete_user, setup_groups, setup_social_auth | | **Media** | collectstatic, optimize_static, download_photos, move_photos | | **Trending** | calculate_trending, update_trending, calculate_new_content | | **Development** | rundev, setup_dev, test_location, cleanup_test_data | | **Security** | security_audit | ### Common Workflows #### Initial Setup ```bash uv run manage.py migrate uv run manage.py createsuperuser uv run manage.py setup_groups uv run manage.py seed_initial_data uv run manage.py create_sample_data --minimal uv run manage.py warm_cache ``` #### Development Reset ```bash uv run manage.py reset_db uv run manage.py migrate uv run manage.py create_sample_data uv run manage.py warm_cache ``` #### Production Deployment ```bash uv run manage.py migrate uv run manage.py collectstatic --noinput uv run manage.py validate_settings --strict uv run manage.py warm_cache ``` #### Cache Refresh ```bash uv run manage.py clear_cache uv run manage.py warm_cache uv run manage.py calculate_trending ``` See [Management Commands Reference](../docs/MANAGEMENT_COMMANDS.md) for complete documentation. ## Database ### Entity Relationships - **Parks** have Operators (required) and PropertyOwners (optional) - **Rides** belong to Parks and may have Manufacturers/Designers - **Users** can create submissions and moderate content - **Reviews** are linked to Parks or Rides with user attribution ### Migrations ```bash # Create migrations uv run manage.py makemigrations # Apply migrations uv run manage.py migrate # Show migration status uv run manage.py showmigrations ``` ## Security Security features implemented: - **CORS** configured for API access - **CSRF** protection enabled - **JWT** token authentication for API - **Session** authentication for web - **Rate limiting** on API endpoints - **Input validation** and sanitization - **Security headers** (HSTS, CSP, etc.) ## Performance Performance optimizations: - **Database query optimization** with custom managers - **Redis caching** for frequent queries - **Background tasks** with Celery - **Connection pooling** for database - **HTMX partials** for minimal data transfer ## Debugging ### Development Tools - **Django Debug Toolbar** - Request/response inspection - **Django Extensions** - Additional management commands - **Silk profiler** - Performance analysis ### Logging Logs are written to: - Console (development) - Files in `logs/` directory (production) - Sentry (production, if configured) ## Contributing 1. Follow Django coding standards 2. Write tests for new features 3. Update documentation 4. Run linting: `uv run ruff check .` 5. Format code: `uv run black .` --- See [Main Documentation](../docs/README.md) for complete project documentation.