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

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 <username>

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