thrillwiki_django_no_react/shared/docs/memory-bank/systemPatterns.md

System Patterns

Architectural Patterns

MVT Implementation

1. Models

   • Use abstract base classes for common fields
   • Implement custom model managers for complex queries
   • Define clear relationships and constraints
   • Include field-level validation

2. Views

   • Prefer class-based views
   • Use mixins for shared functionality
   • Implement proper permission checks
   • Handle HTMX requests explicitly

3. Templates

   • Maintain hierarchy with base templates
   • Use partial templates for HTMX responses
   • Implement component-based structure
   • Follow progressive enhancement

Design Patterns

Data Access

1. Query Patterns

   • Use select_related() for foreign keys
   • Implement prefetch_related() for reverse relationships
   • Create custom model managers
   • Optimize database queries

2. Caching Strategy

   • Cache template fragments
   • Implement model-level caching
   • Use Redis for session storage
   • Cache invalidation rules

Historical Tracking

• All model changes create immutable pghistory events
• Events contain:
  • Full object state snapshot
  • Contextual metadata (user, request fingerprint)
  • Semantic event label (created, updated, deleted)
• Middleware integration:

  # core/middleware.py
  pghistory.context(lambda request: {
      'user': str(request.user) if request.user.is_authenticated else None,
      'ip': request.META.get('REMOTE_ADDR'),
      'user_agent': request.META.get('HTTP_USER_AGENT')
  })
  

Frontend Patterns

1. HTMX Integration

   <!-- Partial Update Pattern -->
   <div hx-get="/endpoint"
        hx-trigger="event"
        hx-target="#target">
   

2. AlpineJS Components

   <!-- State Management Pattern -->
   <div x-data="{ state: {} }"
        x-init="state = await fetchData()">
   

3. Tailwind Components

   <!-- Component Structure -->
   <div class="component-wrapper">
      <div class="component-header"></div>
      <div class="component-content"></div>
   </div>
   

Authentication Patterns

User Management

1. Custom User Model

   • Extended user profiles
   • Role-based permissions
   • Activity tracking
   • Profile customization

2. Authentication Flow

   • Login/registration process
   • Password reset workflow
   • Email verification
   • Session management

Content Management

Moderation Flow

1. Submission Process

   • Content validation
   • Automatic checks
   • Manual review queue
   • Approval workflow

2. Review System

   • Rating framework
   • Media handling
   • User verification
   • Content filtering

Error Handling

Backend Errors

1. Exception Handling

   try:
       # Operation
   except SpecificException as e:
       # Specific handling
   except Exception as e:
       # Generic handling
   

2. Response Patterns

   # Success Response
   return JsonResponse({'status': 'success', 'data': data})
   
   # Error Response
   return JsonResponse({'status': 'error', 'message': str(e)})
   

Frontend Errors

1. User Feedback
   • Toast notifications
   • Inline validation
   • Form feedback
   • Error states

Testing Patterns

Unit Tests

class ModelTests(TestCase):
    def setUp(self):
        # Test setup
        
    def test_specific_functionality(self):
        # Test implementation

Integration Tests

class ViewTests(TestCase):
    def setUp(self):
        self.client = Client()
        
    def test_view_functionality(self):
        # Test implementation

Development Workflows

Package Management

IMPORTANT: When adding Python packages to the project, only use UV:

uv add <package>

Do not attempt to install packages using any other method (pip, poetry, etc.).

Development Server Management

Server Startup Process IMPORTANT: Always execute the following command exactly as shown to start the development server:

lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; uv run manage.py tailwind runserver

Note: These steps must be executed in this exact order as a single command to ensure consistent behavior.

Feature Development

1. Planning

   • Technical specification
   • Component design
   • Database schema
   • API endpoints

2. Implementation

   • Model creation
   • View implementation
   • Template design
   • Testing coverage

3. Review Process

   • Code review
   • Testing verification
   • Documentation update
   • Deployment planning