thrillwiki_django_no_react/shared/docs/memory-bank/features/search-system.md

Site-Wide Search System Architecture

1. Architectural Overview

• Filter-First Approach: Utilizes django-filter for robust filtering capabilities
• Modular Design:

  # filters.py
  class ParkFilter(django_filters.FilterSet):
      search = django_filters.CharFilter(method='filter_search')
  
      class Meta:
          model = Park
          fields = {
              'state': ['exact', 'in'],
              'rating': ['gte', 'lte'],
          }
  
      def filter_search(self, queryset, name, value):
          return queryset.filter(
              Q(name__icontains=value) | 
              Q(description__icontains=value)
          )
  

2. Enhanced Backend Components

Search Endpoint (/search/)

# views.py
class AdaptiveSearchView(TemplateView):
    template_name = "search/results.html"
    
    def get_queryset(self):
        return Park.objects.all()

    def get_filterset(self):
        return ParkFilter(self.request.GET, queryset=self.get_queryset())

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        filterset = self.get_filterset()
        context['results'] = filterset.qs
        context['filters'] = filterset.form
        return context

3. Plugin Integration

Recommended django-filter Extensions

# settings.py
INSTALLED_APPS += [
    'django_filters',
    'django_filters_addons',  # For custom widgets
    'rangefilter',            # For date/number ranges
]

# filters.py
class EnhancedParkFilter(ParkFilter):
    rating_range = django_filters.RangeFilter(field_name='rating')
    features = django_filters.MultipleChoiceFilter(
        field_name='features__slug',
        widget=HorizontalCheckboxSelectMultiple,
        lookup_expr='contains'
    )
    
    class Meta(ParkFilter.Meta):
        fields = ParkFilter.Meta.fields + ['rating_range', 'features']

4. Frontend Filter Rendering

<!-- templates/search/filters.html -->
<form hx-get="/search/" hx-target="#search-results" hx-swap="outerHTML">
    {{ filters.form.as_p }}
    <button type="submit">Apply Filters</button>
</form>

<!-- Dynamic filter updates -->
<div hx-trigger="filter-update from:body" 
     hx-get="/search/filters/" 
     hx-swap="innerHTML">
</div>

5. Benefits of django-filter Integration

• Built-in validation for filter parameters
• Automatic form generation
• Complex lookup expressions
• Reusable filter components
• Plugin ecosystem support

6. Security Considerations

• Input sanitization using django's built-in escaping
• Query parameter whitelisting via FilterSet definitions
• Rate limiting on autocomplete endpoint (using django-ratelimit)
• Permission-aware queryset filtering

7. Performance Optimization

• Select related/prefetch_related in FilterSet querysets
• Caching filter configurations
• Indexing recommendations for filtered fields
• Pagination integration with django-filter

8. Testing Strategy

• FilterSet validation tests
• HTMX interaction tests
• Cross-browser filter UI tests
• Performance load testing

9. Style Integration

• Custom filter form templates matching Tailwind design
• Responsive filter controls grid
• Accessible form labels and error messages
• Dark mode support

10. Expansion Framework

• Registry pattern for adding new FilterSets
• Dynamic filter discovery system
• Plugin configuration templates
• Analytics integration points