## Mandatory Development Rules

### API Organization
- **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. Avoid creating separate top-level API endpoints - nest them under existing domains instead.

### Data Model Rules
- **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")
  - Individual rides reference BOTH the model (what product) and type (how it operates)
  - Ride types must be available for ALL ride categories, not just roller coasters

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

### ThrillWiki Project Rules
- **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
- **Tracking**: All models use pghistory for change tracking and TrackedModel base class
- **Slugs**: Unique within scope (park slugs global, ride slugs within park, ride model slugs within manufacturer)
- **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
- **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 DOCUMENTATION RULE
- CRITICAL: After every change, it is MANDATORY to update docs/frontend.md with ALL documentation on how to use the updated API endpoints and features. Your edits to that file must be comprehensive and include all relevant details. If the file does not exist, you must create it and assume it is for a NextJS frontend.
- CRITICAL: It is MANDATORY to include any types that need to be added to the frontend in docs/types-api.ts for NextJS as the file would appear in `src/types/api.ts` in the NextJS project exactly. Again, create it if it does not exist. Make sure it is in sync with docs/api.ts. Full type safety.
- CRITICAL: It is MANDATORY to include any new API endpoints in docs/lib-api.ts for NextJS as the file would appear in `/src/lib/api.ts` in the NextJS project exactly. Again, create it if it does not exist. Make sure it is in sync with docs/types.ts. Full type safety.

### CRITICAL DATA RULE
- **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.

### CRITICAL DOMAIN SEPARATION RULE
- **OPERATORS AND PROPERTY_OWNERS ARE FOR PARKS ONLY**: 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/` showing a global list of parks with all possible fields.
  - Rides: `/parks/{park_slug}/rides/{ride_slug}/` and `/rides/` showing a global list of rides with all possible fields.
  - Parks Companies: `/parks/operators/{operator_slug}/` and `/parks/owners/{owner_slug}/` and `/parks/operators/` and `/parks/owners/` showing a global list of park operators or owners respectively with filter options based on all fields.
  - Rides Companies: `/rides/manufacturers/{manufacturer_slug}/` and `/rides/designers/{designer_slug}/` and `/rides/manufacturers/` and `/rides/designers/` showing a global list of ride manufacturers or designers respectively with filter options based on all fields.
- **NEVER mix these domains** - this is a fundamental and DANGEROUS business rule violation.

### CRITICAL PHOTO MANAGEMENT RULE
- **Use CloudflareImagesField**: All photo uploads must use CloudflareImagesField with variants and transformations.
- **Photo Types**: Clearly define and use photo types (e.g., banner, card) for all images.
- **Attribution Fields**: Include attribution fields for all photos, specifying the source and copyright information.
- **Primary Photo Logic**: Implement logic to determine the primary photo for each model, ensuring consistency across the application.