thrillwiki_django_no_react/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

### Static Files Organization
1. Directory Structure
   - `static/` - Source static files (CSS, JS, images, etc.)
   - `staticfiles/` - Collected files (generated by collectstatic)

2. File Management Rules
   - Place all source static files in `static/` directory
   - Never directly modify `staticfiles/` directory
   - Use Django's `static` template tag for references
   - Run collectstatic before deployment

3. Benefits of Separation
   - Clear distinction between source and compiled files
   - Prevents confusion in development vs production
   - Follows Django best practices
   - Simplifies deployment process

## 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:
  ```python
  # 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
   ```html
   <!-- Partial Update Pattern -->
   <div hx-get="/endpoint"
        hx-trigger="event"
        hx-target="#target">
   ```

2. AlpineJS Components
   ```html
   <!-- State Management Pattern -->
   <div x-data="{ state: {} }"
        x-init="state = await fetchData()">
   ```

3. Tailwind Components
   ```html
   <!-- 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
   ```python
   try:
       # Operation
   except SpecificException as e:
       # Specific handling
   except Exception as e:
       # Generic handling
   ```

2. Response Patterns
   ```python
   # 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
```python
class ModelTests(TestCase):
    def setUp(self):
        # Test setup
        
    def test_specific_functionality(self):
        # Test implementation
```

### Integration Tests
```python
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:
```bash
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:
```bash
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