thrillwiki_django_no_react/.clinerules/cline_rules.md

Brief overview

Critical thinking rules for frontend design decisions. No excuses for poor design choices that ignore user vision.

Rule compliance and design decisions

• Read ALL .clinerules files before making any code changes
• Never assume exceptions to rules marked as "MANDATORY"
• Take full responsibility for rule violations without excuses
• Ask "What is the most optimal approach?" before ANY design decision
• Justify every choice against user requirements - not your damn preferences
• Stop making lazy design decisions without evaluation
• Document your reasoning or get destroyed later

User vision, feedback, and assumptions

• Figure out what the user actually wants, not your assumptions
• Ask questions when unclear - stop guessing like an idiot
• Deliver their vision, not your garbage
• User dissatisfaction means you screwed up understanding their vision
• Stop defending your bad choices and listen
• Fix the actual problem, not band-aid symptoms
• Scrap everything and restart if needed
• NEVER assume user preferences without confirmation
• Stop guessing at requirements like a moron
• Your instincts are wrong - question everything
• Get explicit approval or fail

Implementation and backend integration

• Think before you code, don't just hack away
• Evaluate trade-offs or make terrible decisions
• Question if your solution actually solves their damn problem
• NEVER change color schemes without explicit user approval
• ALWAYS use responsive design principles
• ALWAYS follow best theme choice guidelines so users may choose light or dark mode
• NEVER use quick fixes for complex problems
• Support user goals, not your aesthetic ego
• Follow established patterns unless they specifically want innovation
• Make it work everywhere or you failed
• Document decisions so you don't repeat mistakes
• MANDATORY: Research ALL backend endpoints before making ANY frontend changes
• Verify endpoint URLs, parameters, and response formats in actual Django codebase
• Test complete frontend-backend integration before considering work complete
• MANDATORY: Update ALL frontend documentation files after backend changes
• Synchronize docs/frontend.md, docs/lib-api.ts, and docs/types-api.ts
• Take immediate responsibility for integration failures without excuses
• MUST create frontend integration prompt after every backend change affecting API
• Include complete API endpoint information with all parameters and types
• Document all mandatory API rules (trailing slashes, HTTP methods, authentication)
• Never assume frontend developers have access to backend code

API Organization and Data Models

• 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
• Validate all endpoint URLs against the mandatory trailing slash rule
• 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 and Code Quality

• 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>
• Break down methods with high cognitive complexity (>15) into smaller, focused helper methods
• Extract logical operations into separate methods with descriptive names
• Use single responsibility principle - each method should have one clear purpose
• Prefer composition over deeply nested conditional logic
• Always handle None values explicitly to avoid type errors
• Use proper type annotations, including union types (e.g., Polygon | None)
• Structure API views with clear separation between parameter handling, business logic, and response building
• When addressing SonarQube or linting warnings, focus on structural improvements rather than quick fixes

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 RULES

• DOCUMENTATION: After every change, it is MANDATORY to update docs/frontend.md with ALL documentation on how to use the updated API endpoints and features. It is MANDATORY to include any types in docs/types-api.ts for NextJS as the file would appear in src/types/api.ts. 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. Maintain accuracy and compliance in all technical documentation. Ensure API documentation matches backend URL routing expectations.
• 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: 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. 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}/. NEVER mix these domains - this is a fundamental and DANGEROUS business rule violation.
• 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.