thrillwiki_django_no_react/.clinerules/thrillwiki-context.md

ThrillWiki Django App Context

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

• Backend: Django 5.0+ with DRF, PostgreSQL + PostGIS, Redis caching, Celery tasks
• Frontend: HTMX + AlpineJS + Tailwind CSS + Django-Cotton (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 Structure

• Parks Domain: parks/, companies (OPERATOR/PROPERTY_OWNER roles only)
• Rides Domain: rides/, companies (MANUFACTURER/DESIGNER roles only)
• Core Apps: accounts/, media/, moderation/, core/
• CRITICAL: Never mix park/ride company roles - fundamental business rule

Key Patterns

• Models: All inherit TrackedModel, use SluggedModel for slugs with history
• API: Nested URLs (/parks/{slug}/rides/{slug}/), mandatory trailing slashes
• Choices: RichChoiceField with metadata (color, icon, description, css_class)
• Photos: CloudflareImagesField with photo types and attribution
• Location: PostGIS for geographic data, separate location models

Development Commands

• Server: uv run manage.py runserver_plus (NOT python manage.py)
• Migrations: uv run manage.py makemigrations/migrate
• Packages: uv add <package> (NOT pip install)
• Management: Always use uv run manage.py <command>

API Rules

• Authentication: Token-based with role hierarchy (USER/MODERATOR/ADMIN/SUPERUSER)
• Filtering: Comprehensive filtering on 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
• NEVER MOCK DATA: All responses must use real database queries

Rich Choice Objects (MANDATORY)

• Use RichChoiceField(choice_group="group_name", domain="domain_name")
• Define choices in domain-specific choices.py using RichChoice dataclass
• Register with register_choices() function in domain __init__.py
• Include rich metadata: color, icon, description, css_class minimum
• NO tuple-based choices allowed anywhere in codebase

Frontend Constraints

• HTMX for dynamic updates, AlpineJS for client state, Tailwind for styling
• Progressive enhancement approach required
• Must support latest 2 versions of major browsers
• Performance targets: FCP < 1.5s, TTI < 2s, Core Web Vitals compliance