thrillwiki_django_no_react/.clinerules/thrillwiki-context.md

description, author, version, globs, tags

description	author	version	globs	tags
Comprehensive ThrillWiki Django project context including architecture, development patterns, business rules, and mandatory Context7 MCP integration workflow	ThrillWiki Development Team	2.0	**/*.py **/*.html **/*.js **/*.css **/*.md	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