thrillwiki_django_no_react/backend/README.md

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

```html
<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:

```html
<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](../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.