ThrillWiki - Django + HTMX Application

A comprehensive theme park and roller coaster information system built with Django and HTMX, providing a progressive enhancement approach to modern web development.

Architecture Overview

ThrillWiki is a Django monolith with HTMX-driven interactivity, not a traditional SPA. This architecture provides:

• Server-side rendering for SEO and initial page load performance
• Progressive enhancement with HTMX for dynamic updates without full page reloads
• REST API for programmatic access and potential mobile app integration
• Alpine.js for minimal client-side state (limited to form validation and UI toggles)

thrillwiki/
├── backend/                 # Django application (main codebase)
│   ├── apps/               # Modular Django applications
│   │   ├── accounts/       # User management and authentication
│   │   ├── api/v1/         # REST API endpoints
│   │   ├── core/           # Shared utilities and base classes
│   │   ├── location/       # Geographic data and services
│   │   ├── media/          # File management (Cloudflare Images)
│   │   ├── moderation/     # Content moderation workflows
│   │   ├── parks/          # Theme park data and operations
│   │   └── rides/          # Ride information and relationships
│   ├── config/             # Django settings and configuration
│   │   ├── django/         # Environment-specific settings
│   │   └── settings/       # Modular settings modules
│   ├── templates/          # Django templates with HTMX
│   │   ├── components/     # Reusable UI components
│   │   ├── htmx/           # HTMX partial templates
│   │   └── layouts/        # Base layout templates
│   └── static/             # Static assets (CSS, JS, images)
├── shared/                  # Shared resources
│   ├── scripts/            # Development and deployment scripts
│   └── media/              # Shared media files
├── architecture/            # Architecture documentation
├── docs/                    # Project documentation
└── tests/                   # Test files

Technology Stack

Technology	Version	Purpose
Django	5.2.8+	Web framework
Django REST Framework	3.15.2+	API framework
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+ with uv for package management
• PostgreSQL 14+ with PostGIS extension
• Redis 6+ for caching and sessions

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd thrillwiki
   

2. Install dependencies

   cd backend
   uv sync --frozen  # Use locked versions for reproducibility
   

3. Environment configuration

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

4. Database setup

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

5. Start development server

   uv run manage.py runserver
   

The application will be available at http://localhost:8000.

Project Structure Details

Django Applications

App	Description
accounts	User authentication, profiles, preferences, and social auth
api/v1	RESTful API endpoints with OpenAPI documentation
core	Shared utilities, managers, middleware, and services
location	Geographic models, geocoding, and map services
media	Cloudflare Images integration and file management
moderation	Content review workflows and moderation queue
parks	Theme park models, views, and related operations
rides	Ride models, coaster statistics, and ride history

HTMX Patterns

ThrillWiki uses HTMX for server-driven interactivity:

• Partial templates (*_partial.html) for dynamic content updates
• HX-Trigger for cross-component communication
• hx-indicator with skeleton loaders for loading states
• Field-level validation via HTMX for form feedback

See HTMX Patterns for detailed conventions.

Hybrid API/HTML Endpoints

Many views serve dual purposes:

• HTML response for browser requests (template rendering)
• JSON response for API requests (DRF serialization)

This is achieved through content negotiation and hybrid view mixins.

Development Workflow

Running the Development Server

cd backend
uv run manage.py runserver

Django Management Commands

# Database operations
uv run manage.py migrate
uv run manage.py makemigrations
uv run manage.py createsuperuser

# Static files
uv run manage.py collectstatic

# Validate configuration
uv run manage.py validate_settings

# Testing
uv run manage.py test

Code Quality

# Format code
uv run black .
uv run isort .

# Lint code
uv run ruff check .
uv run flake8 .

# Type checking
uv run pyright

Configuration

Environment Variables

ThrillWiki uses environment variables for configuration. Key variables:

Variable	Description
SECRET_KEY	Django secret key (required)
DEBUG	Debug mode (True/False)
DATABASE_URL	PostgreSQL connection URL
REDIS_URL	Redis connection URL
DJANGO_SETTINGS_MODULE	Settings module to use

See Environment Variables for complete reference.

Settings Architecture

ThrillWiki uses a modular settings architecture:

config/
├── django/              # Environment-specific settings
│   ├── base.py          # Core settings
│   ├── local.py         # Development overrides
│   ├── production.py    # Production overrides
│   └── test.py          # Test overrides
└── settings/            # Modular settings
    ├── cache.py         # Redis caching
    ├── database.py      # Database configuration
    ├── email.py         # Email settings
    ├── logging.py       # Logging configuration
    ├── rest_framework.py # DRF and CORS
    ├── security.py      # Security headers
    └── storage.py       # Static/media files

API Documentation

Interactive Documentation

• Swagger UI: /api/docs/
• ReDoc: /api/redoc/
• OpenAPI Schema: /api/schema/

API Overview

• Base URL: /api/v1/
• Authentication: JWT Bearer tokens or session-based
• Content-Type: application/json

See API Documentation for complete endpoint reference.

Key Features

Park Database

• Comprehensive theme park information worldwide
• Operator and property owner relationships
• Geographic data with PostGIS support
• Operating status and seasonal information

Ride Database

• Complete ride specifications and statistics
• Roller coaster technical data (height, speed, inversions)
• Manufacturer and designer tracking
• Historical status and name changes

User Features

• User authentication with social login (Google, Discord)
• Profile management and preferences
• Review and rating system
• Personalized content and contributions

Content Moderation

• Review and approval workflows
• Moderation queue management
• User moderation actions
• Bulk operations support

API Capabilities

• Full CRUD for all entities
• Advanced filtering and search
• Pagination and sorting
• Rate limiting and caching

Documentation

Core Documentation

• Backend Documentation - Setup and development details
• API Documentation - Complete API reference
• Setup Guide - Comprehensive setup instructions

Configuration

• Environment Variables - Complete reference
• Secret Management - Secret handling

Architecture

• Architecture Decisions - ADRs for key decisions
• Deployment Guide - Production deployment
• Health Checks - Monitoring endpoints

Accessibility

• Keyboard Navigation - Keyboard shortcuts
• Screen Reader Testing - Testing checklist
• Component Patterns - Accessible patterns

Testing

Running Tests

# 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

Accessibility Testing

# Run accessibility tests
uv run manage.py test backend.tests.accessibility

Deployment

Development Environment

# Start development server
uv run manage.py runserver

# Full development setup
./shared/scripts/dev/setup-dev.sh

Production Deployment

See Deployment Guide for detailed production setup instructions.

Key production requirements:

• DEBUG=False
• SSL/HTTPS enforcement
• Redis for caching and sessions
• PostgreSQL with connection pooling
• Proper secret management

Production Checklist

See Production Checklist for deployment verification.

Contributing

We welcome contributions! Please follow these guidelines:

1. Development Setup - Follow the setup instructions above
2. Code Standards - Follow Django coding standards and use provided linters
3. Testing - Write tests for new features
4. Documentation - Update documentation as needed

Quick Contribution Start

# Fork and clone the repository
git clone https://github.com/your-username/thrillwiki.git
cd thrillwiki

# Set up development environment
cd backend && uv sync

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes and test
uv run manage.py test

# Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with Django + HTMX for the theme park and roller coaster community