# 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.