thrillwiki_django_no_react/docs/README.md

# 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](https://docs.astral.sh/uv/) for package management
- **PostgreSQL 14+** with PostGIS extension
- **Redis 6+** for caching and sessions

### Development Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd thrillwiki
   ```

2. **Install dependencies**
   ```bash
   cd backend
   uv sync --frozen  # Use locked versions for reproducibility
   ```

3. **Environment configuration**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

4. **Database setup**
   ```bash
   uv run manage.py migrate
   uv run manage.py createsuperuser
   ```

5. **Start development server**
   ```bash
   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](./htmx-patterns.md) 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

```bash
cd backend
uv run manage.py runserver
```

### Django Management Commands

```bash
# 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

```bash
# 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](./configuration/environment-variables.md) 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](./THRILLWIKI_API_DOCUMENTATION.md) 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](../backend/README.md) - Setup and development details
- [API Documentation](./THRILLWIKI_API_DOCUMENTATION.md) - Complete API reference
- [Setup Guide](./SETUP_GUIDE.md) - Comprehensive setup instructions

### Configuration
- [Environment Variables](./configuration/environment-variables.md) - Complete reference
- [Secret Management](./configuration/secret-management.md) - Secret handling

### Architecture
- [Architecture Decisions](./architecture/) - ADRs for key decisions
- [Deployment Guide](../architecture/deployment-guide.md) - Production deployment
- [Health Checks](./HEALTH_CHECKS.md) - Monitoring endpoints

### Accessibility
- [Keyboard Navigation](./accessibility/keyboard-navigation.md) - Keyboard shortcuts
- [Screen Reader Testing](./accessibility/screen-reader-testing.md) - Testing checklist
- [Component Patterns](./accessibility/component-patterns.md) - Accessible patterns

## Management Commands

ThrillWiki provides 50+ management commands for various operations. See [Backend README - Management Commands](../backend/README.md#management-commands) for complete documentation.

### Quick Reference

```bash
# Configuration
uv run manage.py validate_settings

# Cache management
uv run manage.py warm_cache
uv run manage.py clear_cache

# Data seeding
uv run manage.py seed_initial_data
uv run manage.py create_sample_data

# Development
uv run manage.py rundev
uv run manage.py setup_dev
```

See [Management Commands Reference](./MANAGEMENT_COMMANDS.md) for complete command documentation.

## Testing

### Running Tests

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

### Accessibility Testing

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

## Deployment

### Development Environment

```bash
# Start development server
uv run manage.py runserver

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

### Production Deployment

See [Deployment Guide](../architecture/deployment-guide.md) 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](./PRODUCTION_CHECKLIST.md) 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

```bash
# 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](../LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/your-repo/thrillwiki/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-repo/thrillwiki/discussions)

---

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