thrillwiki_django_no_react/cline_docs/permanent_rules.md

Permanent Development Rules

API Organization Rules

MANDATORY NESTING ORGANIZATION

All API directory structures MUST match URL nesting patterns. No exceptions. If URLs are nested like /api/v1/rides/manufacturers/<slug>/, then the directory structure must be backend/apps/api/v1/rides/manufacturers/.

Data Model Rules

RIDE TYPES vs RIDE MODELS DISTINCTION

CRITICAL RULE: Ride Types and Ride Models are completely separate concepts that must never be conflated:

Ride Types (Operational Classifications)

• Definition: How a ride operates or what experience it provides
• Scope: Applies to ALL ride categories (not just roller coasters)
• Examples:
  • Roller Coasters: "inverted", "suspended", "wing", "dive", "flying", "spinning", "wild mouse"
  • Dark Rides: "trackless", "boat", "omnimover", "simulator", "walk-through"
  • Flat Rides: "spinning", "swinging", "drop tower", "ferris wheel", "carousel"
  • Water Rides: "log flume", "rapids", "water coaster", "splash pad"
  • Transport: "monorail", "gondola", "train", "people mover"
• Storage: Should be stored as type classifications for each ride category
• Purpose: Describes the ride experience and operational characteristics

Ride Models (Manufacturer Products)

• Definition: Specific designs/products manufactured by companies
• Scope: Catalog of available ride designs that can be purchased and installed
• Examples: "B&M Dive Coaster", "Vekoma Boomerang", "RMC I-Box", "Intamin Blitz", "Mack PowerSplash"
• Storage: Stored in RideModel table with manufacturer relationships
• Purpose: Product catalog for ride installations

Relationship

• Individual ride installations reference BOTH:
  • The RideModel (what specific product/design was purchased)
  • The ride type classification (how it operates within its category)
• A ride model can have a type, but they serve different purposes in the data structure
• Example: "Silver Star at Europa-Park" is a "B&M Hyper Coaster" (model) that is a "sit-down" type roller coaster

Implementation Requirements

• Ride types must be available for ALL ride categories, not just roller coasters
• Current system only has roller coaster types in RollerCoasterStats.roller_coaster_type
• Need to extend type classifications to all ride categories
• Maintain clear separation between type (how it works) and model (what product it is)

UI Component Standards

DJANGO-COTTON COMPONENT REQUIREMENT

MANDATORY RULE: All new card components and reusable UI patterns MUST be implemented using Django Cotton components.

Component Organization

• Location: All Django Cotton components must be stored in templates/cotton/
• Naming: Component files must use snake_case naming (e.g., park_card.html, ride_card.html)
• Documentation: Every component must include comprehensive documentation comments with usage examples
• Parameters: Components must use <c-vars> for parameter definition with sensible defaults

Standardized Card Components

The following standardized components are available and MUST be used instead of custom implementations:

Park Card Component (templates/cotton/park_card.html)

• Usage: <c-park_card park=park view_mode="grid" />
• Features: Supports both list and grid modes, status badges, operator info, stats
• Required for: All park listing and display use cases

Ride Card Component (templates/cotton/ride_card.html)

• Usage: <c-ride_card ride=ride />
• Features: Image handling, status badges, stats grid, special features, manufacturer info
• Required for: All ride listing and display use cases

Implementation Requirements

• No Duplication: Do not create new card templates that duplicate existing Cotton component functionality
• Consistent Styling: All components must follow established Tailwind CSS patterns and design system
• Responsive Design: Components must include proper responsive breakpoints and mobile-first design
• Accessibility: All components must include proper ARIA labels and semantic HTML
• Performance: Components should be optimized for rendering performance and minimize template complexity

Legacy Template Migration

• Existing Templates: When modifying existing templates, refactor them to use Cotton components
• Gradual Migration: Priority should be given to high-traffic pages and frequently modified templates
• Testing Required: All migrations must include thorough testing to ensure functionality preservation

Exceptions

The only acceptable reasons to NOT use Django Cotton components are:

• Technical limitations that prevent Cotton usage in specific contexts
• Performance-critical pages where component overhead is measurably problematic
• Temporary prototyping (with clear migration path to Cotton components)

All exceptions must be documented with justification and include a plan for eventual Cotton migration.

Enforcement

These rules are MANDATORY and must be followed in all development work. Any violation should be immediately corrected.