# ThrillWiki Backend

Django REST API backend for the ThrillWiki monorepo.

## 🏗️ Architecture

This backend follows Django best practices with a modular app structure:

```
backend/
├── apps/                 # Django applications
│   ├── accounts/         # User management
│   ├── parks/           # Theme park data
│   ├── rides/           # Ride information
│   ├── moderation/      # Content moderation
│   ├── location/        # Geographic data
│   ├── media/           # File management
│   ├── email_service/   # Email functionality
│   └── core/            # Core utilities
├── config/              # Django configuration
│   ├── django/          # Settings files
│   └── settings/        # Modular settings
├── templates/           # Django templates
├── static/              # Static files
└── tests/               # Test files
```

## 🛠️ Technology Stack

- **Django 5.0+** - Web framework
- **Django REST Framework** - API framework
- **PostgreSQL** - Primary database
- **Redis** - Caching and sessions
- **UV** - Python package management
- **Celery** - Background task processing

## 🚀 Quick Start

### Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) package manager
- PostgreSQL 14+
- Redis 6+

### Setup

1. **Install dependencies**
   ```bash
   cd backend
   uv sync
   ```

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

## 🔧 Configuration

### Environment Variables

Required environment variables:

```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost/thrillwiki

# Django
SECRET_KEY=your-secret-key
DEBUG=True
DJANGO_SETTINGS_MODULE=config.django.local

# Redis
REDIS_URL=redis://localhost:6379

# Email (optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
```

### Settings Structure

- `config/django/base.py` - Base settings
- `config/django/local.py` - Development settings
- `config/django/production.py` - Production settings
- `config/django/test.py` - Test settings

## 📁 Apps Overview

### Core Apps

- **accounts** - User authentication and profile management
- **parks** - Theme park models and operations
- **rides** - Ride information and relationships
- **core** - Shared utilities and base classes

### Support Apps

- **moderation** - Content moderation workflows
- **location** - Geographic data and services
- **media** - File upload and management
- **email_service** - Email sending and templates

## 🔌 API Endpoints

Base URL: `http://localhost:8000/api/`

### Authentication
- `POST /auth/login/` - User login
- `POST /auth/logout/` - User logout
- `POST /auth/register/` - User registration

### Parks
- `GET /parks/` - List parks
- `GET /parks/{id}/` - Park details
- `POST /parks/` - Create park (admin)

### Rides
- `GET /rides/` - List rides
- `GET /rides/{id}/` - Ride details
- `GET /parks/{park_id}/rides/` - Rides by park

## 🧪 Testing

```bash
# Run all tests
uv run manage.py test

# Run specific app tests
uv run manage.py test apps.parks

# Run with coverage
uv run coverage run manage.py test
uv run coverage report
```

## 🔧 Management Commands

Custom management commands:

```bash
# Import park data
uv run manage.py import_parks data/parks.json

# Generate test data
uv run manage.py generate_test_data

# Clean up expired sessions
uv run manage.py clearsessions
```

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

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

- CORS configured for frontend integration
- CSRF protection enabled
- JWT token authentication
- Rate limiting on API endpoints
- Input validation and sanitization

## 📈 Performance

- Database query optimization
- Redis caching for frequent queries
- Background task processing with Celery
- Database connection pooling

## 🚀 Deployment

See the [Deployment Guide](../shared/docs/deployment/) for production setup.

## 🐛 Debugging

### Development Tools

- Django Debug Toolbar
- Django Extensions
- Silk profiler for performance analysis

### Logging

Logs are written to:
- Console (development)
- Files in `logs/` directory (production)
- External logging service (production)

## 🤝 Contributing

1. Follow Django coding standards
2. Write tests for new features
3. Update documentation
4. Run linting: `uv run flake8 .`
5. Format code: `uv run black .`