thrillwiki_django_no_react/.clinerules/thrillwiki-context.md

---
description: Comprehensive ThrillWiki Django project context including architecture, development patterns, business rules, and mandatory Context7 MCP integration workflow
author: ThrillWiki Development Team
version: 2.0
globs: ["**/*.py", "**/*.html", "**/*.js", "**/*.css", "**/*.md"]
tags: ["django", "architecture", "api-design", "business-rules", "context7-integration", "thrillwiki"]
---

# ThrillWiki Django Project Context

## Objective
This rule provides comprehensive context for the ThrillWiki project, defining core architecture patterns, business rules, development workflows, and mandatory integration requirements. It serves as the primary reference for maintaining consistency across all ThrillWiki development activities.

## Project Overview
ThrillWiki is a comprehensive theme park database platform with user-generated content, expert moderation, and rich media support. Built with Django REST Framework, it serves 120+ API endpoints for parks, rides, companies, and user management.

## Core Architecture

### Technology Stack
- **Backend**: Django 5.0+ with DRF, PostgreSQL + PostGIS, Redis caching, Celery tasks
- **Frontend**: HTMX + AlpineJS + Tailwind CSS + Django-Cotton 
  - 🚨 **CRITICAL**: NO React/Vue/Angular allowed
- **Media**: Cloudflare Images using Direct Upload with variants and transformations
- **Tracking**: pghistory for all model changes, TrackedModel base class
- **Choices**: Rich Choice Objects system (NEVER use Django tuple choices)

### Domain Architecture
- **Parks Domain**: `parks/`, companies (OPERATOR/PROPERTY_OWNER roles only)
- **Rides Domain**: `rides/`, companies (MANUFACTURER/DESIGNER roles only)
- **Core Apps**: `accounts/`, `media/`, `moderation/`, `core/`
- 🚨 **CRITICAL BUSINESS RULE**: Never mix park/ride company roles - fundamental business rule violation

## Development Patterns

### Model Patterns
- **Base Classes**: All models MUST inherit from TrackedModel
- **Slug Handling**: Use SluggedModel for slugs with history tracking
- **Location Data**: Use PostGIS for geographic data, separate location models
- **Media Fields**: Use CloudflareImagesField for all image handling

### API Design Patterns
- **URL Structure**: Nested URLs (`/parks/{slug}/rides/{slug}/`)
- **Trailing Slashes**: MANDATORY trailing slashes on all endpoints
- **Authentication**: Token-based with role hierarchy (USER/MODERATOR/ADMIN/SUPERUSER)
- **Filtering**: Comprehensive filtering - rides (25+ parameters), parks (15+ parameters)
- **Responses**: Standard DRF pagination, rich error responses with details
- **Caching**: Multi-level (Redis, CDN, browser) with signal-based invalidation

### Choice System (MANDATORY)
- **Implementation**: `RichChoiceField(choice_group="group_name", domain="domain_name")`
- **Definition**: Domain-specific `choices.py` using RichChoice dataclass
- **Registration**: `register_choices()` function in domain `__init__.py`
- **Required Metadata**: color, icon, description, css_class (minimum)
- 🚨 **FORBIDDEN**: NO tuple-based choices allowed anywhere in codebase

## Development Commands

### Package Management
- **Python Packages**: `uv add <package>` (NOT `pip install`)
- **Server**: `uv run manage.py runserver_plus` (NOT `python manage.py`)
- **Migrations**: `uv run manage.py makemigrations/migrate`
- **Management**: ALWAYS use `uv run manage.py <command>`

## Business Rules

### Company Role Separation
- **Parks Domain**: Only OPERATOR and PROPERTY_OWNER roles
- **Rides Domain**: Only MANUFACTURER and DESIGNER roles
- 🚨 **CRITICAL**: Never allow cross-domain company roles

### Data Integrity
- **Model Changes**: All must be tracked via pghistory
- **API Responses**: MUST use real database data (NEVER MOCK DATA)
- **Geographic Data**: MUST use PostGIS for accuracy

## Frontend Constraints

### Architecture Requirements
- **HTMX**: Dynamic updates and AJAX interactions
- **AlpineJS**: Client-side state management
- **Tailwind CSS**: Styling framework
- **Progressive Enhancement**: Required approach

### Performance Targets
- **First Contentful Paint**: < 1.5s
- **Time to Interactive**: < 2s
- **Compliance**: Core Web Vitals compliance
- **Browser Support**: Latest 2 versions of major browsers

## Context7 MCP Integration (MANDATORY)

### Requirement
🚨 **CRITICAL**: ALWAYS use Context7 MCP for documentation lookups before making changes

### Libraries Requiring Context7
- **tailwindcss**: CSS utility classes, responsive design, component styling
- **django**: Models, views, forms, URL patterns, Django-specific patterns
- **django-cotton**: Component creation, template organization, Cotton-specific syntax
- **htmx**: Dynamic updates, form handling, AJAX interactions
- **alpinejs**: Client-side state management, reactive data, JavaScript interactions
- **django-rest-framework**: API design, serializers, viewsets, DRF patterns
- **postgresql**: Database queries, PostGIS functions, advanced SQL features
- **postgis**: Geographic data handling and spatial queries
- **redis**: Caching strategies, session management, performance optimization

### Mandatory Workflow Steps
1. **Before editing/creating code**: Query Context7 for relevant library documentation
2. **During debugging**: Use Context7 to verify syntax, patterns, and best practices
3. **When implementing new features**: Reference Context7 for current API and method signatures
4. **For performance issues**: Consult Context7 for optimization techniques and patterns
5. **For geographic data handling**: Use Context7 for PostGIS functions and best practices
6. **For caching strategies**: Refer to Context7 for Redis patterns and best practices
7. **For database queries**: Utilize Context7 for PostgreSQL best practices and advanced SQL features

### Mandatory Scenarios
- Creating new Django models or API endpoints
- Implementing HTMX dynamic functionality
- Writing AlpineJS reactive components
- Designing responsive layouts with Tailwind CSS
- Creating Django-Cotton components
- Debugging CSS, JavaScript, or Django issues
- Implementing caching or database optimizations
- Handling geographic data with PostGIS
- Utilizing Redis for session management
- Implementing real-time features with WebSockets

### Context7 Commands
1. **Resolve Library**: Always call `Context7:resolve-library-id` first to get correct library ID
2. **Get Documentation**: Then use `Context7:get-library-docs` with appropriate topic parameter

### Example Topics by Library
- **tailwindcss**: responsive design, flexbox, grid, animations
- **django**: models, views, forms, admin, signals
- **django-cotton**: components, templates, slots, props
- **htmx**: hx-get, hx-post, hx-swap, hx-trigger, hx-target
- **alpinejs**: x-data, x-show, x-if, x-for, x-model
- **django-rest-framework**: serializers, viewsets, routers, permissions
- **postgresql**: joins, indexes, transactions, window functions
- **postgis**: geospatial queries, distance calculations, spatial indexes
- **redis**: caching strategies, pub/sub, data structures

## Code Quality Standards

### Model Requirements
- All models MUST inherit from TrackedModel
- Use SluggedModel for entities with slugs and history tracking
- Always use RichChoiceField instead of Django choices
- Use CloudflareImagesField for all image handling
- Use PostGIS fields and separate location models for geographic data

### API Requirements
- MUST include trailing slashes and follow nested pattern
- All responses MUST use real database queries
- Implement comprehensive filtering and pagination
- Use signal-based cache invalidation

### Development Workflow
- Use uv for all Python package operations
- Use runserver_plus for enhanced development server
- Always use `uv run` for Django management commands
- All functionality MUST work with progressive enhancement