# 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 ```bash # Database operations uv run manage.py migrate uv run manage.py makemigrations uv run manage.py createsuperuser uv run manage.py showmigrations # Static files uv run manage.py collectstatic # Configuration validation uv run manage.py validate_settings # Cache management uv run manage.py warm_cache # Data management uv run manage.py import_parks data/parks.json uv run manage.py generate_test_data ``` ## 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.