# Comprehensive Ride Filtering System Design

## Overview
This document outlines the design for a robust ride filtering system with PostgreSQL full-text search capabilities, organized in logical filter categories with a beautiful Tailwind 4 UI.

## Filter Categories

### 1. Search & Text Filters
- **Main Search Bar**: Full-text search across name, description, park name using PostgreSQL SearchVector
- **Advanced Search**: Separate fields for ride name, park name, description
- **Fuzzy Search**: TrigramSimilarity for typo-tolerant searching

### 2. Basic Ride Information
- **Category**: Multi-select dropdown (Roller Coaster, Dark Ride, Flat Ride, Water Ride, Transport, Other)
- **Status**: Multi-select dropdown (Operating, Temporarily Closed, SBNO, Closing, Permanently Closed, Under Construction, Demolished, Relocated)

### 3. Date Filters
- **Opening Date Range**: Date picker for from/to dates
- **Closing Date Range**: Date picker for from/to dates  
- **Status Since**: Date picker for from/to dates

### 4. Height & Safety Requirements
- **Minimum Height**: Range slider (30-90 inches)
- **Maximum Height**: Range slider (30-90 inches)
- **Height Requirement Type**: No requirement, minimum only, maximum only, both

### 5. Performance Metrics
- **Capacity per Hour**: Range slider (0-5000+ people)
- **Ride Duration**: Range slider (0-600+ seconds)
- **Average Rating**: Range slider (1-10 stars)

### 6. Location & Relationships
- **Park**: Multi-select autocomplete dropdown
- **Park Area**: Multi-select dropdown (filtered by selected parks)
- **Manufacturer**: Multi-select autocomplete dropdown
- **Designer**: Multi-select autocomplete dropdown
- **Ride Model**: Multi-select autocomplete dropdown

### 7. Roller Coaster Specific (only shown when RC category selected)
- **Height**: Range slider (0-500+ feet)
- **Length**: Range slider (0-10000+ feet)
- **Speed**: Range slider (0-150+ mph)
- **Inversions**: Range slider (0-20+)
- **Max Drop Height**: Range slider (0-500+ feet)
- **Track Material**: Multi-select (Steel, Wood, Hybrid)
- **Coaster Type**: Multi-select (Sit Down, Inverted, Flying, Stand Up, Wing, Dive, Family, Wild Mouse, Spinning, 4th Dimension, Other)
- **Launch Type**: Multi-select (Chain Lift, LSM Launch, Hydraulic Launch, Gravity, Other)

### 8. Company Information (when manufacturer/designer filters are used)
- **Company Founded**: Date range picker
- **Company Roles**: Multi-select (Manufacturer, Designer, Operator, Property Owner)
- **Rides Count**: Range slider (1-500+)
- **Coasters Count**: Range slider (1-200+)

## Sorting Options
- **Name** (A-Z, Z-A)
- **Opening Date** (Newest, Oldest)
- **Average Rating** (Highest, Lowest)
- **Height** (Tallest, Shortest) - for roller coasters
- **Speed** (Fastest, Slowest) - for roller coasters
- **Capacity** (Highest, Lowest)
- **Recently Updated** (using pghistory)
- **Relevance** (for text searches using SearchRank)

## UI/UX Design Principles

### Layout Structure
- **Desktop**: Sidebar filter panel (collapsible) + main content area
- **Mobile**: Overlay filter modal with bottom sheet design
- **Filter Organization**: Collapsible sections with clean headers and icons

### Tailwind 4 Design System
- **Color Scheme**: Modern neutral palette with theme support
- **Typography**: Clear hierarchy with proper contrast
- **Spacing**: Consistent spacing scale (4, 8, 16, 24, 32px)
- **Interactive Elements**: Smooth transitions and hover states
- **Form Controls**: Custom-styled inputs, dropdowns, sliders

### Dark Mode Support
- Full dark mode implementation using Tailwind's dark: variants
- Theme toggle in header
- Proper contrast ratios for accessibility
- Dark-friendly color selections for data visualization

### Responsive Design
- **Mobile First**: Progressive enhancement approach
- **Breakpoints**: sm (640px), md (768px), lg (1024px), xl (1280px)
- **Touch Friendly**: Larger touch targets on mobile
- **Collapsible Filters**: Smart grouping on smaller screens

## Technical Implementation

### Backend Architecture
1. **Search Service**: Django service layer for search logic
2. **PostgreSQL Features**: SearchVector, SearchQuery, SearchRank, GIN indexes
3. **Fuzzy Matching**: TrigramSimilarity for typo tolerance
4. **Caching**: Redis for popular filter combinations
5. **Pagination**: Efficient pagination with search ranking

### Frontend Features
1. **HTMX Integration**: Real-time filtering without full page reloads
2. **URL Persistence**: Filter state preserved in URL parameters
3. **Autocomplete**: Intelligent suggestions for text fields
4. **Filter Counts**: Show result counts for each filter option
5. **Active Filters**: Visual indicators of applied filters
6. **Reset Functionality**: Clear individual or all filters

### Performance Optimizations
1. **Database Indexes**: GIN indexes on search vectors
2. **Query Optimization**: Efficient JOIN strategies
3. **Caching Layer**: Popular searches cached in Redis
4. **Debounced Input**: Prevent excessive API calls
5. **Lazy Loading**: Load expensive filter options on demand

## Accessibility Features
- **Keyboard Navigation**: Full keyboard support for all controls
- **Screen Readers**: Proper ARIA labels and descriptions
- **Color Contrast**: WCAG AA compliance
- **Focus Management**: Clear focus indicators
- **Alternative Text**: Descriptive labels for all controls

## Search Algorithm Details

### PostgreSQL Full-Text Search
```sql
-- Search vector combining multiple fields with weights
search_vector = (
    setweight(to_tsvector('english', name), 'A') ||
    setweight(to_tsvector('english', park.name), 'B') ||
    setweight(to_tsvector('english', description), 'C') ||
    setweight(to_tsvector('english', manufacturer.name), 'D')
)

-- Search query with ranking
SELECT *, ts_rank(search_vector, query) as rank
FROM rides
WHERE search_vector @@ query
ORDER BY rank DESC, name
```

### Trigram Similarity
```sql
-- Fuzzy matching for typos
SELECT *
FROM rides
WHERE similarity(name, 'search_term') > 0.3
ORDER BY similarity(name, 'search_term') DESC
```

## Filter State Management
- **URL Parameters**: All filter state stored in URL for shareability
- **Local Storage**: Remember user preferences
- **Session State**: Maintain state during browsing session
- **Bookmark Support**: Full filter state can be bookmarked

## Testing Strategy
1. **Unit Tests**: Individual filter components
2. **Integration Tests**: Full filtering workflows
3. **Performance Tests**: Large dataset filtering
4. **Accessibility Tests**: Screen reader and keyboard testing
5. **Mobile Tests**: Touch interface testing
6. **Browser Tests**: Cross-browser compatibility

## Future Enhancements
1. **Saved Filters**: User accounts can save filter combinations
2. **Advanced Analytics**: Popular filter combinations tracking
3. **Machine Learning**: Personalized filter suggestions
4. **Export Features**: Export filtered results to CSV/PDF
5. **Comparison Mode**: Side-by-side ride comparisons