kayrozen.com
forked from
smokesignal.events/smokesignal
i18n+filtering fork - fluent-templates v2
1//! # Event Filtering Module
2//!
3//! Advanced event search and filtering capabilities with faceted search, internationalization,
4//! and caching integration for high-performance event discovery.
5//!
6//! This module provides a comprehensive filtering system that allows users to discover events
7//! based on multiple criteria including location, time, event type, and custom attributes.
8//! The system is designed for performance with intelligent caching and optimized database queries.
9//!
10//! ## Architecture
11//!
12//! The filtering system is organized around several key components:
13//!
14//! ### Core Components
15//! - **[`service`]** - Main filtering service with caching and coordination
16//! - **[`query_builder`]** - SQL query construction for complex filtering operations
17//! - **[`criteria`]** - Filter criteria definition and validation
18//! - **[`facets`]** - Faceted search functionality for guided discovery
19//!
20//! ### Support Systems
21//! - **[`hydration`]** - Result enrichment with additional data and i18n
22//! - **[`errors`]** - Filtering-specific error handling and user feedback
23//!
24//! ## Features
25//!
26//! ### Faceted Search
27//! Multi-dimensional filtering with dynamic facet generation:
28//! - **Location Facets** - Geographic regions, cities, venues
29//! - **Time Facets** - Date ranges, time of day, duration
30//! - **Category Facets** - Event types, topics, target audiences
31//! - **Status Facets** - Event status (scheduled, cancelled, etc.)
32//! - **Dynamic Facets** - Generated based on current result set
33//!
34//! ### Performance Optimization
35//! - **Query Optimization** - Efficient SQL generation with proper indexing
36//! - **Result Caching** - Redis-based caching of frequently accessed filters
37//! - **Pagination** - Memory-efficient handling of large result sets
38//! - **Incremental Loading** - Progressive result enhancement
39//!
40//! ### Internationalization
41//! - **Localized Facets** - Facet names and values in user's language
42//! - **Geographic Localization** - Location names in appropriate language
43//! - **Time Zone Support** - Automatic time zone conversion for events
44//! - **Cultural Formatting** - Date and time formatting per locale
45//!
46//! ### Search Capabilities
47//! - **Full-Text Search** - Content search across event titles and descriptions
48//! - **Fuzzy Matching** - Tolerance for spelling variations and typos
49//! - **Synonym Support** - Expanded search with related terms
50//! - **Stemming** - Language-appropriate word stemming
51//!
52//! ## Filter Types
53//!
54//! ### Geographic Filters
55//! - **Radius Search** - Events within specified distance
56//! - **Bounding Box** - Events within rectangular area
57//! - **Administrative** - City, state, country-based filtering
58//! - **Venue Type** - Indoor, outdoor, virtual venue classification
59//!
60//! ### Temporal Filters
61//! - **Date Range** - Events within specific date spans
62//! - **Time of Day** - Morning, afternoon, evening events
63//! - **Duration** - Short, medium, long-duration events
64//! - **Recurrence** - One-time vs. recurring events
65//!
66//! ### Content Filters
67//! - **Category** - Event category and subcategory
68//! - **Tags** - User-defined and system-generated tags
69//! - **Language** - Event content language
70//! - **Accessibility** - Accessibility features and requirements
71//!
72//! ## Example Usage
73//!
74//! ```rust,no_run
75//! use smokesignal::filtering::{service::FilteringService, criteria::FilterCriteria};
76//! use chrono::{DateTime, Utc};
77//!
78//! async fn search_events() -> anyhow::Result<()> {
79//! let filtering_service = FilteringService::new(pool, cache).await?;
80//!
81//! // Create filter criteria
82//! let criteria = FilterCriteria::builder()
83//! .location_radius(40.7128, -74.0060, 10.0) // 10km around NYC
84//! .date_range(
85//! DateTime::<Utc>::from_timestamp(1640995200, 0).unwrap(),
86//! DateTime::<Utc>::from_timestamp(1672531200, 0).unwrap()
87//! )
88//! .categories(vec!["technology", "networking"])
89//! .language("en-US")
90//! .build()?;
91//!
92//! // Perform search with facets
93//! let results = filtering_service.search_events(criteria, true).await?;
94//!
95//! println!("Found {} events", results.events.len());
96//! for facet in results.facets {
97//! println!("Facet {}: {} options", facet.name, facet.values.len());
98//! }
99//!
100//! Ok(())
101//! }
102//! ```
103//!
104//! ## Caching Strategy
105//!
106//! The filtering system uses a multi-layered caching approach:
107//! - **Query Result Cache** - Cached search results for common queries
108//! - **Facet Cache** - Pre-computed facet values for popular filters
109//! - **Metadata Cache** - Event metadata and enrichment data
110//! - **User Cache** - Personalized filter preferences and history
111
112pub mod criteria;
113pub mod errors;
114pub mod facets;
115pub mod hydration;
116pub mod query_builder;
117pub mod service;
118
119#[cfg(test)]
120mod cache_integration_test;
121
122#[cfg(test)]
123mod mode_status_integration_test;
124
125#[cfg(test)]
126mod i18n_integration_test;
127
128pub use criteria::*;
129pub use errors::*;
130pub use facets::*;
131pub use hydration::*;
132pub use query_builder::*;
133pub use service::*;
134
135/// Filter context for passing common dependencies
136#[derive(Debug, Clone)]
137pub struct FilterContext {
138 pub pool: crate::storage::StoragePool,
139 pub language: crate::http::middleware_i18n::Language,
140}
141
142impl FilterContext {
143 pub fn new(pool: crate::storage::StoragePool, language: crate::http::middleware_i18n::Language) -> Self {
144 Self { pool, language }
145 }
146}