From 33f54860001fb64eabf7cf7ff94c92dbb7956f44 Mon Sep 17 00:00:00 2001 From: pacnpal <183241239+pacnpal@users.noreply.github.com> Date: Tue, 23 Sep 2025 19:35:57 -0400 Subject: [PATCH] Add comprehensive context documentation for ThrillWiki Django app --- .clinerules/cline_rules.md | 49 ------------------------------ .clinerules/thrillwiki-context.md | 50 +++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 49 deletions(-) create mode 100644 .clinerules/thrillwiki-context.md diff --git a/.clinerules/cline_rules.md b/.clinerules/cline_rules.md index 3567e568..c1b05b15 100644 --- a/.clinerules/cline_rules.md +++ b/.clinerules/cline_rules.md @@ -1,51 +1,3 @@ -## 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 @@ -85,7 +37,6 @@ Critical thinking rules for frontend design decisions. No excuses for poor desig - **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. diff --git a/.clinerules/thrillwiki-context.md b/.clinerules/thrillwiki-context.md new file mode 100644 index 00000000..0516ea9c --- /dev/null +++ b/.clinerules/thrillwiki-context.md @@ -0,0 +1,50 @@ +## ThrillWiki Django App Context + +### Project Overview +ThrillWiki is a comprehensive theme park database platform with user-generated content, expert moderation, and rich media support. Built with Django REST Framework, it serves 120+ API endpoints for parks, rides, companies, and user management. + +### Core Architecture +- **Backend**: Django 5.0+ with DRF, PostgreSQL + PostGIS, Redis caching, Celery tasks +- **Frontend**: HTMX + AlpineJS + Tailwind CSS + Django-Cotton (NO React/Vue/Angular allowed) +- **Media**: Cloudflare Images using Direct Upload with variants and transformations +- **Tracking**: pghistory for all model changes, TrackedModel base class +- **Choices**: Rich Choice Objects system (NEVER use Django tuple choices) + +### Domain Structure +- **Parks Domain**: parks/, companies (OPERATOR/PROPERTY_OWNER roles only) +- **Rides Domain**: rides/, companies (MANUFACTURER/DESIGNER roles only) +- **Core Apps**: accounts/, media/, moderation/, core/ +- **CRITICAL**: Never mix park/ride company roles - fundamental business rule + +### Key Patterns +- **Models**: All inherit TrackedModel, use SluggedModel for slugs with history +- **API**: Nested URLs (/parks/{slug}/rides/{slug}/), mandatory trailing slashes +- **Choices**: RichChoiceField with metadata (color, icon, description, css_class) +- **Photos**: CloudflareImagesField with photo types and attribution +- **Location**: PostGIS for geographic data, separate location models + +### Development Commands +- **Server**: `uv run manage.py runserver_plus` (NOT python manage.py) +- **Migrations**: `uv run manage.py makemigrations/migrate` +- **Packages**: `uv add ` (NOT pip install) +- **Management**: Always use `uv run manage.py ` + +### API Rules +- **Authentication**: Token-based with role hierarchy (USER/MODERATOR/ADMIN/SUPERUSER) +- **Filtering**: Comprehensive filtering on rides (25+ parameters), parks (15+ parameters) +- **Responses**: Standard DRF pagination, rich error responses with details +- **Caching**: Multi-level (Redis, CDN, browser) with signal-based invalidation +- **NEVER MOCK DATA**: All responses must use real database queries + +### Rich Choice Objects (MANDATORY) +- Use `RichChoiceField(choice_group="group_name", domain="domain_name")` +- Define choices in domain-specific `choices.py` using RichChoice dataclass +- Register with `register_choices()` function in domain `__init__.py` +- Include rich metadata: color, icon, description, css_class minimum +- NO tuple-based choices allowed anywhere in codebase + +### Frontend Constraints +- HTMX for dynamic updates, AlpineJS for client state, Tailwind for styling +- Progressive enhancement approach required +- Must support latest 2 versions of major browsers +- Performance targets: FCP < 1.5s, TTI < 2s, Core Web Vitals compliance \ No newline at end of file