filter module usage documentation

docs/filter_module_USAGE.md

···
+# Event Filtering System - Usage and Integration Guide
+
+## Overview
+This document provides practical examples and integration patterns for using the event filtering system in the smokesignal-eTD application. It demonstrates how to implement filtering with both dynamic user inputs and fixed query templates for specific use cases.
+
+## Table of Contents
+1. [Basic Usage Patterns](#basic-usage-patterns)
+2. [Fixed Query Templates](#fixed-query-templates)
+3. [Integration Examples](#integration-examples)
+4. [API Reference](#api-reference)
+5. [Template Usage](#template-usage)
+6. [Performance Optimization](#performance-optimization)
+7. [Error Handling](#error-handling)
+
+## Basic Usage Patterns
+
+### 1. Simple Text Search
+```rust
+use crate::filtering::{EventFilterCriteria, FilteringService};
+
+// Basic text search for "conference" events
+let criteria = EventFilterCriteria {
+    search_text: Some("conference".to_string()),
+    ..Default::default()
+};
+
+let service = FilteringService::new(pool.clone());
+let results = service.filter_events(&criteria, 1, 20).await?;
+```
+
+### 2. Date Range Filtering
+```rust
+use chrono::{DateTime, Utc};
+
+let criteria = EventFilterCriteria {
+    date_from: Some(DateTime::parse_from_rfc3339("2025-06-01T00:00:00Z")?.with_timezone(&Utc)),
+    date_to: Some(DateTime::parse_from_rfc3339("2025-12-31T23:59:59Z")?.with_timezone(&Utc)),
+    ..Default::default()
+};
+
+let results = service.filter_events(&criteria, 1, 50).await?;
+```
+
+### 3. Location-Based Filtering
+```rust
+let criteria = EventFilterCriteria {
+    location_text: Some("Montreal".to_string()),
+    location_radius_km: Some(25.0),
+    ..Default::default()
+};
+
+let results = service.filter_events(&criteria, 1, 30).await?;
+```
+
+## Fixed Query Templates
+
+### Template 1: Upcoming Tech Events
+Perfect for embedding in tech-focused pages or newsletters.
+
+```rust
+use crate::filtering::{EventFilterCriteria, FilteringService};
+use chrono::{DateTime, Utc, Duration};
+
+pub struct TechEventsTemplate;
+
+impl TechEventsTemplate {
+    /// Get upcoming tech events in the next 30 days
+    pub async fn get_upcoming_tech_events(
+        service: &FilteringService,
+        location: Option<String>,
+    ) -> Result<FilteredEventsResult, FilteringError> {
+        let now = Utc::now();
+        let thirty_days = now + Duration::days(30);
+        
+        let criteria = EventFilterCriteria {
+            // Tech-related keywords
+            search_text: Some("technology OR programming OR developer OR startup OR AI OR software OR web OR mobile OR data".to_string()),
+            
+            // Only future events
+            date_from: Some(now),
+            date_to: Some(thirty_days),
+            
+            // Optional location filter
+            location_text: location,
+            location_radius_km: Some(50.0),
+            
+            // Sort by date ascending (soonest first)
+            sort_by: Some("date_asc".to_string()),
+            
+            ..Default::default()
+        };
+        
+        // Get first 10 results
+        service.filter_events(&criteria, 1, 10).await
+    }
+}
+
+// Usage example
+let tech_events = TechEventsTemplate::get_upcoming_tech_events(
+    &service, 
+    Some("San Francisco".to_string())
+).await?;
+```
+
+### Template 2: Weekend Community Events
+Ideal for community pages or local event discovery.
+
+```rust
+pub struct CommunityEventsTemplate;
+
+impl CommunityEventsTemplate {
+    /// Get community events happening this weekend
+    pub async fn get_weekend_community_events(
+        service: &FilteringService,
+        city: &str,
+    ) -> Result<FilteredEventsResult, FilteringError> {
+        let now = Utc::now();
+        let days_until_saturday = (6 - now.weekday().num_days_from_monday()) % 7;
+        let saturday = now + Duration::days(days_until_saturday as i64);
+        let sunday = saturday + Duration::days(1);
+        
+        let criteria = EventFilterCriteria {
+            // Community-focused keywords
+            search_text: Some("community OR meetup OR networking OR social OR volunteer OR local OR neighborhood".to_string()),
+            
+            // Weekend timeframe
+            date_from: Some(saturday),
+            date_to: Some(sunday + Duration::hours(23) + Duration::minutes(59)),
+            
+            // Specific city
+            location_text: Some(city.to_string()),
+            location_radius_km: Some(25.0),
+            
+            // Sort by popularity (most RSVPs first)
+            sort_by: Some("popularity_desc".to_string()),
+            
+            ..Default::default()
+        };
+        
+        service.filter_events(&criteria, 1, 15).await
+    }
+}
+
+// Usage example
+let weekend_events = CommunityEventsTemplate::get_weekend_community_events(
+    &service,
+    "Toronto"
+).await?;
+```
+
+### Template 3: Free Educational Events
+Great for student portals or educational institutions.
+
+```rust
+pub struct EducationalEventsTemplate;
+
+impl EducationalEventsTemplate {
+    /// Get free educational events in the next 60 days
+    pub async fn get_free_educational_events(
+        service: &FilteringService,
+        subject_area: Option<String>,
+    ) -> Result<FilteredEventsResult, FilteringError> {
+        let now = Utc::now();
+        let sixty_days = now + Duration::days(60);
+        
+        let mut search_terms = vec![
+            "workshop", "seminar", "lecture", "course", "tutorial", 
+            "training", "learning", "education", "free", "no cost"
+        ];
+        
+        // Add subject-specific terms if provided
+        if let Some(subject) = &subject_area {
+            search_terms.push(subject);
+        }
+        
+        let criteria = EventFilterCriteria {
+            search_text: Some(search_terms.join(" OR ")),
+            
+            // Next 60 days
+            date_from: Some(now),
+            date_to: Some(sixty_days),
+            
+            // Filter for likely free events
+            // This could be enhanced with a dedicated "free" field
+            
+            // Sort by date ascending
+            sort_by: Some("date_asc".to_string()),
+            
+            ..Default::default()
+        };
+        
+        service.filter_events(&criteria, 1, 20).await
+    }
+}
+
+// Usage examples
+let programming_workshops = EducationalEventsTemplate::get_free_educational_events(
+    &service,
+    Some("programming".to_string())
+).await?;
+
+let general_education = EducationalEventsTemplate::get_free_educational_events(
+    &service,
+    None
+).await?;
+```
+
+### Template 4: Tonight's Events
+Perfect for "what's happening tonight" widgets.
+
+```rust
+pub struct TonightEventsTemplate;
+
+impl TonightEventsTemplate {
+    /// Get events happening tonight in a specific area
+    pub async fn get_tonights_events(
+        service: &FilteringService,
+        location: &str,
+        radius_km: f64,
+    ) -> Result<FilteredEventsResult, FilteringError> {
+        let now = Utc::now();
+        let tonight_start = now.date_naive().and_hms_opt(18, 0, 0)
+            .unwrap().and_local_timezone(Utc).unwrap();
+        let tonight_end = now.date_naive().and_hms_opt(23, 59, 59)
+            .unwrap().and_local_timezone(Utc).unwrap();
+        
+        let criteria = EventFilterCriteria {
+            // Evening/night events
+            date_from: Some(tonight_start),
+            date_to: Some(tonight_end),
+            
+            // Location constraint
+            location_text: Some(location.to_string()),
+            location_radius_km: Some(radius_km),
+            
+            // Sort by start time
+            sort_by: Some("date_asc".to_string()),
+            
+            ..Default::default()
+        };
+        
+        service.filter_events(&criteria, 1, 10).await
+    }
+}
+
+// Usage example
+let tonight = TonightEventsTemplate::get_tonights_events(
+    &service,
+    "Vancouver",
+    15.0
+).await?;
+```
+
+## Integration Examples
+
+### 1. Axum Route Handler with Fixed Template
+
+```rust
+use axum::{extract::State, response::Html, Extension};
+use crate::http::context::WebContext;
+use crate::filtering::FilteringService;
+
+pub async fn handle_tech_events_page(
+    State(context): State<WebContext>,
+    Extension(user_location): Extension<Option<String>>,
+) -> Result<Html<String>, AppError> {
+    let service = FilteringService::new(context.storage_pool.clone());
+    
+    // Use the fixed template
+    let events = TechEventsTemplate::get_upcoming_tech_events(
+        &service,
+        user_location
+    ).await?;
+    
+    // Render template
+    let rendered = context.handlebars.render("tech_events_page", &json!({
+        "events": events.events,
+        "facets": events.facets,
+        "total_count": events.total_count,
+        "page_title": "Upcoming Tech Events"
+    }))?;
+    
+    Ok(Html(rendered))
+}
+```
+
+### 2. HTMX Widget for Dashboard
+
+```rust
+pub async fn handle_weekend_events_widget(
+    State(context): State<WebContext>,
+    Query(params): Query<HashMap<String, String>>,
+) -> Result<Html<String>, AppError> {
+    let city = params.get("city").cloned()
+        .unwrap_or_else(|| "Montreal".to_string());
+    
+    let service = FilteringService::new(context.storage_pool.clone());
+    let events = CommunityEventsTemplate::get_weekend_community_events(
+        &service,
+        &city
+    ).await?;
+    
+    // Render as HTMX partial
+    let rendered = context.handlebars.render("weekend_events_widget", &json!({
+        "events": events.events,
+        "city": city
+    }))?;
+    
+    Ok(Html(rendered))
+}
+```
+
+### 3. API Endpoint for Mobile App
+
+```rust
+use axum::Json;
+use serde_json::json;
+
+pub async fn api_tonight_events(
+    State(context): State<WebContext>,
+    Query(params): Query<HashMap<String, String>>,
+) -> Result<Json<Value>, AppError> {
+    let location = params.get("location")
+        .ok_or_else(|| AppError::BadRequest("location parameter required".to_string()))?;
+    
+    let radius = params.get("radius")
+        .and_then(|r| r.parse::<f64>().ok())
+        .unwrap_or(10.0);
+    
+    let service = FilteringService::new(context.storage_pool.clone());
+    let events = TonightEventsTemplate::get_tonights_events(
+        &service,
+        location,
+        radius
+    ).await?;
+    
+    Ok(Json(json!({
+        "success": true,
+        "data": {
+            "events": events.events,
+            "total_count": events.total_count,
+            "location": location,
+            "radius_km": radius
+        }
+    })))
+}
+```
+
+## API Reference
+
+### FilteringService Methods
+
+```rust
+impl FilteringService {
+    /// Create a new filtering service instance
+    pub fn new(pool: sqlx::PgPool) -> Self;
+    
+    /// Filter events with full criteria support
+    pub async fn filter_events(
+        &self,
+        criteria: &EventFilterCriteria,
+        page: i64,
+        page_size: i64,
+    ) -> Result<FilteredEventsResult, FilteringError>;
+    
+    /// Get facet counts for refining filters
+    pub async fn calculate_facets(
+        &self,
+        criteria: &EventFilterCriteria,
+    ) -> Result<EventFacets, FilteringError>;
+    
+    /// Hydrate events with additional data
+    pub async fn hydrate_events(
+        &self,
+        events: &mut [Event],
+        strategy: HydrationStrategy,
+    ) -> Result<(), FilteringError>;
+}
+```
+
+### EventFilterCriteria Fields
+
+```rust
+pub struct EventFilterCriteria {
+    /// Text search across event content
+    pub search_text: Option<String>,
+    
+    /// Filter by date range
+    pub date_from: Option<DateTime<Utc>>,
+    pub date_to: Option<DateTime<Utc>>,
+    
+    /// Location-based filtering
+    pub location_text: Option<String>,
+    pub location_latitude: Option<f64>,
+    pub location_longitude: Option<f64>,
+    pub location_radius_km: Option<f64>,
+    
+    /// Event type filtering
+    pub event_types: Option<Vec<String>>,
+    
+    /// Organizer filtering
+    pub organizer_handles: Option<Vec<String>>,
+    
+    /// Sorting options
+    pub sort_by: Option<String>, // "date_asc", "date_desc", "popularity_desc", "relevance"
+    
+    /// Language filtering
+    pub languages: Option<Vec<String>>,
+}
+```
+
+## Template Usage
+
+### 1. Tech Events Page Template
+
+```handlebars
+{{!-- templates/tech_events_page.en-us.html --}}
+<div class="tech-events-page">
+    <h1>{{tr "tech-events-title"}}</h1>
+    <p class="subtitle">{{tr "tech-events-subtitle"}}</p>
+    
+    <div class="events-grid">
+        {{#each events}}
+        <div class="event-card">
+            <h3><a href="/{{organizer_handle}}/{{rkey}}">{{title}}</a></h3>
+            <p class="event-date">{{format_date start_time}}</p>
+            <p class="event-location">{{location.name}}</p>
+            <p class="event-description">{{truncate description 150}}</p>
+        </div>
+        {{/each}}
+    </div>
+    
+    {{#if (gt total_count events.length)}}
+    <p class="more-events">
+        <a href="/events?search=technology OR programming OR developer">
+            {{tr "view-all-tech-events"}}
+        </a>
+    </p>
+    {{/if}}
+</div>
+```
+
+### 2. Weekend Events Widget
+
+```handlebars
+{{!-- templates/weekend_events_widget.en-us.incl.html --}}
+<div class="weekend-widget" 
+     hx-get="/api/weekend-events?city={{city}}" 
+     hx-trigger="every 30m">
+    
+    <h4>{{tr "this-weekend-in"}} {{city}}</h4>
+    
+    {{#if events}}
+    <ul class="event-list">
+        {{#each events}}
+        <li class="event-item">
+            <a href="/{{organizer_handle}}/{{rkey}}">
+                <strong>{{title}}</strong>
+                <span class="event-time">{{format_time start_time}}</span>
+            </a>
+        </li>
+        {{/each}}
+    </ul>
+    {{else}}
+    <p class="no-events">{{tr "no-weekend-events"}}</p>
+    {{/if}}
+</div>
+```
+
+### 3. Tonight's Events Notification
+
+```handlebars
+{{!-- templates/tonight_events_notification.en-us.incl.html --}}
+{{#if events}}
+<div class="notification is-info">
+    <button class="delete" onclick="this.parentElement.style.display='none'"></button>
+    <strong>{{tr "happening-tonight"}}:</strong>
+    {{#each events}}
+        <a href="/{{organizer_handle}}/{{rkey}}">{{title}}</a>{{#unless @last}}, {{/unless}}
+    {{/each}}
+</div>
+{{/if}}
+```
+
+## Performance Optimization
+
+### 1. Caching Fixed Templates
+
+```rust
+use redis::AsyncCommands;
+
+impl TechEventsTemplate {
+    pub async fn get_cached_tech_events(
+        service: &FilteringService,
+        redis: &mut redis::aio::Connection,
+        location: Option<String>,
+    ) -> Result<FilteredEventsResult, FilteringError> {
+        let cache_key = format!("tech_events:{}", 
+            location.as_deref().unwrap_or("global"));
+        
+        // Try cache first
+        if let Ok(cached) = redis.get::<_, String>(&cache_key).await {
+            if let Ok(events) = serde_json::from_str(&cached) {
+                return Ok(events);
+            }
+        }
+        
+        // Fallback to database
+        let events = Self::get_upcoming_tech_events(service, location).await?;
+        
+        // Cache for 15 minutes
+        let serialized = serde_json::to_string(&events)?;
+        let _: () = redis.setex(&cache_key, 900, serialized).await?;
+        
+        Ok(events)
+    }
+}
+```
+
+### 2. Background Updates
+
+```rust
+use tokio::time::{interval, Duration};
+
+pub async fn start_template_cache_updater(
+    service: FilteringService,
+    redis_pool: redis::aio::ConnectionManager,
+) {
+    let mut interval = interval(Duration::from_secs(600)); // 10 minutes
+    
+    loop {
+        interval.tick().await;
+        
+        // Update popular templates
+        let cities = vec!["Montreal", "Toronto", "Vancouver", "Calgary"];
+        
+        for city in cities {
+            if let Ok(mut conn) = redis_pool.clone().into_connection().await {
+                let _ = TechEventsTemplate::get_cached_tech_events(
+                    &service,
+                    &mut conn,
+                    Some(city.to_string())
+                ).await;
+                
+                let _ = CommunityEventsTemplate::get_weekend_community_events(
+                    &service,
+                    city
+                ).await;
+            }
+        }
+    }
+}
+```
+
+## Error Handling
+
+### 1. Graceful Degradation
+
+```rust
+pub async fn handle_tech_events_safe(
+    service: &FilteringService,
+    location: Option<String>,
+) -> FilteredEventsResult {
+    match TechEventsTemplate::get_upcoming_tech_events(service, location).await {
+        Ok(events) => events,
+        Err(err) => {
+            tracing::error!("Failed to fetch tech events: {}", err);
+            
+            // Return empty result with error indication
+            FilteredEventsResult {
+                events: vec![],
+                facets: EventFacets::default(),
+                total_count: 0,
+                has_more: false,
+                error_message: Some("Unable to load events at this time".to_string()),
+            }
+        }
+    }
+}
+```
+
+### 2. Fallback Templates
+
+```rust
+impl TechEventsTemplate {
+    pub async fn get_tech_events_with_fallback(
+        service: &FilteringService,
+        location: Option<String>,
+    ) -> Result<FilteredEventsResult, FilteringError> {
+        // Try specific tech events first
+        if let Ok(events) = Self::get_upcoming_tech_events(service, location.clone()).await {
+            if !events.events.is_empty() {
+                return Ok(events);
+            }
+        }
+        
+        // Fallback to broader search
+        let criteria = EventFilterCriteria {
+            search_text: Some("event OR meetup OR conference".to_string()),
+            date_from: Some(Utc::now()),
+            date_to: Some(Utc::now() + Duration::days(30)),
+            location_text: location,
+            location_radius_km: Some(50.0),
+            sort_by: Some("date_asc".to_string()),
+            ..Default::default()
+        };
+        
+        service.filter_events(&criteria, 1, 10).await
+    }
+}
+```
+
+## Integration Checklist
+
+### Before Using Fixed Templates
+
+- [ ] Database migrations applied (`20250530104334_event_filtering_indexes.sql`)
+- [ ] Environment variable `DATABASE_URL` configured
+- [ ] Redis connection available (for caching)
+- [ ] Handlebars templates created for your use case
+- [ ] Localization strings added to `i18n/*/ui.ftl` files
+- [ ] Error handling implemented for your specific needs
+
+### Template Implementation Steps
+
+1. **Define your fixed criteria** in a template struct
+2. **Implement the query method** using `EventFilterCriteria`
+3. **Create the route handler** in your Axum router
+4. **Add the Handlebars template** for rendering
+5. **Add localization strings** for user-facing text
+6. **Implement caching** for frequently-used templates
+7. **Add error handling** and fallback behavior
+8. **Test with realistic data** to verify performance
+
+### Performance Considerations
+
+- **Cache frequently-used templates** (tech events, weekend events)
+- **Use background jobs** to pre-populate cache
+- **Implement fallback queries** for when specific searches return no results
+- **Monitor query performance** and adjust indexes as needed
+- **Consider pagination** for templates that might return many results
+
+---
+
+This guide provides a complete reference for integrating the event filtering system with fixed query templates. The examples demonstrate real-world usage patterns that can be adapted for specific application needs while maintaining performance and user experience.
+
+*Generated: May 30, 2025  
+Author: GitHub Copilot  
+Version: Usage Guide v1.0*