thrillwiki_django_no_react/.clinerules/cline_rules.md

description, author, version, globs, tags

description	author	version	globs	tags
Core ThrillWiki development rules covering API organization, data models, development commands, code quality standards, and critical business rules	ThrillWiki Development Team	1.0	**/*.py apps/**/* thrillwiki/**/* **/*.md	django api-design code-quality development-commands business-rules

ThrillWiki Core Development Rules

Objective

This rule defines the fundamental development standards, API organization patterns, code quality requirements, and critical business rules that MUST be followed for all ThrillWiki development work. It ensures consistency, maintainability, and adherence to project-specific constraints.

API Organization and Data Models

Mandatory API Structure

• MANDATORY NESTING: All API directory structures MUST match URL nesting patterns. No exceptions.
• NO TOP-LEVEL ENDPOINTS: URLs must be nested under top-level domains
• MANDATORY TRAILING SLASHES: All API endpoints MUST include trailing forward slashes unless ending with query parameters
• Validation Required: Validate all endpoint URLs against the mandatory trailing slash rule

Ride System Architecture

RIDE TYPES vs RIDE MODELS: These are separate concepts for ALL ride categories:

• Ride Types: How rides operate (e.g., "inverted", "trackless", "spinning", "log flume", "monorail")
• Ride Models: Specific manufacturer products (e.g., "B&M Dive Coaster", "Vekoma Boomerang")
• Implementation: Individual rides reference BOTH the model (what product) and type (how it operates)
• Coverage: Ride types MUST be available for ALL ride categories, not just roller coasters

Development Commands and Code Quality

Required Commands

• Django Server: ALWAYS use uv run manage.py runserver_plus instead of python manage.py runserver
• Django Migrations: ALWAYS use uv run manage.py makemigrations and uv run manage.py migrate instead of python manage.py
• Package Management: ALWAYS use uv add <package> instead of pip install <package>
• Django Management: ALWAYS use uv run manage.py <command> instead of python manage.py <command>

Code Quality Standards

• Cognitive Complexity: Break down methods with high cognitive complexity (>15) into smaller, focused helper methods
• Method Extraction: Extract logical operations into separate methods with descriptive names
• Single Responsibility: Each method SHOULD have one clear purpose
• Logic Structure: Prefer composition over deeply nested conditional logic
• Null Handling: ALWAYS handle None values explicitly to avoid type errors
• Type Annotations: Use proper type annotations, including union types (e.g., Polygon | None)
• API Structure: Structure API views with clear separation between parameter handling, business logic, and response building
• Quality Improvements: When addressing SonarQube or linting warnings, focus on structural improvements rather than quick fixes

ThrillWiki Project Rules

Domain Architecture

• Domain Structure: Parks contain rides, rides have models, companies have multiple roles (manufacturer/operator/designer)
• Media Integration: Use CloudflareImagesField for all photo uploads with variants and transformations
• Change Tracking: All models use pghistory for change tracking and TrackedModel base class
• Slug Management: Unique within scope (park slugs global, ride slugs within park, ride model slugs within manufacturer)

Status and Role Management

• Status Management: Rides have operational status (OPERATING, CLOSED_TEMP, SBNO, etc.) with date tracking
• Company Roles: Companies can be MANUFACTURER, OPERATOR, DESIGNER, PROPERTY_OWNER with array field
• Location Data: Use PostGIS for geographic data, separate location models for parks and rides

Technical Patterns

• API Patterns: Use DRF with drf-spectacular, comprehensive serializers, nested endpoints, caching
• Photo Management: Banner/card image references, photo types, attribution fields, primary photo logic
• Search Integration: Text search, filtering, autocomplete endpoints, pagination
• Statistics: Cached stats endpoints with automatic invalidation via Django signals

CRITICAL RULES

Data Integrity (ABSOLUTE)

🚨 NEVER MOCK DATA: You are NEVER EVER to mock any data unless it's ONLY for API schema documentation purposes. All data MUST come from real database queries and actual model instances. Mock data is STRICTLY FORBIDDEN in all API responses, services, and business logic.

Domain Separation (CRITICAL BUSINESS RULE)

🚨 DOMAIN SEPARATION: Company roles OPERATOR and PROPERTY_OWNER are EXCLUSIVELY for parks domain. They SHOULD NEVER be used in rides URLs or ride-related contexts. Only MANUFACTURER and DESIGNER roles are for rides domain.

Correct URL Patterns:

• Parks: /parks/{park_slug}/ and /parks/
• Rides: /parks/{park_slug}/rides/{ride_slug}/ and /rides/
• Parks Companies: /parks/operators/{operator_slug}/ and /parks/owners/{owner_slug}/
• Rides Companies: /rides/manufacturers/{manufacturer_slug}/ and /rides/designers/{designer_slug}/

⚠️ WARNING: NEVER mix these domains - this is a fundamental and DANGEROUS business rule violation.

Photo Management Standards

🚨 PHOTO MANAGEMENT:

• Use CloudflareImagesField for all photo uploads with variants and transformations
• Clearly define and use photo types (e.g., banner, card) for all images
• Include attribution fields for all photos
• Implement logic to determine the primary photo for each model

Verification Checklist

Before implementing any changes, verify:

• All API endpoints have trailing slashes
• Domain separation is maintained (parks vs rides companies)
• No mock data is used outside of schema documentation
• Proper uv commands are used for all Django operations
• Type annotations are complete and accurate
• Methods follow single responsibility principle
• CloudflareImagesField is used for all photo uploads