thrillwiki_django_no_react/backend

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 package manager
• PostgreSQL 14+ with PostGIS extension
• Redis 6+

Setup

1. Install dependencies

   cd backend
   uv sync --frozen  # Use locked versions for reproducibility
   # Or: uv sync     # Allow updates within version constraints
   

2. Environment configuration

   cp .env.example .env
   # Edit .env with your settings
   

3. Database setup

   uv run manage.py migrate
   uv run manage.py createsuperuser
   

4. Start development server

   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:

# 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:

<!-- Trigger event after action -->
<button hx-post="/parks/1/favorite/"
        hx-trigger="click"
        hx-swap="none"
        hx-headers='{"HX-Trigger-After-Settle": "parkFavorited"}'>
    Favorite
</button>

<!-- Listen for event -->
<div hx-get="/parks/favorites/"
     hx-trigger="parkFavorited from:body">
    <!-- Updated on event -->
</div>

Loading Indicators

Skeleton loaders for better UX:

<div hx-get="/parks/" hx-trigger="load" hx-indicator="#loading">
    <div id="loading" class="htmx-indicator">
        {% include "components/skeleton_loader.html" %}
    </div>
</div>

Field-Level Validation

Real-time form validation:

<input name="email"
       hx-post="/validate/email/"
       hx-trigger="blur changed delay:500ms"
       hx-target="next .error-message">
<span class="error-message"></span>

See HTMX Patterns for complete documentation.

Hybrid API/HTML Endpoints

Many views serve dual purposes through content negotiation:

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:

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 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 for complete reference.

Testing

# 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

# 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

# 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 for complete project documentation.