Initial commit

references/SEARCH_REFERENCE.md

@@ -0,0 +1,192 @@
+# MainSearchBar Search Logic Reference
+
+## Overview
+
+The MainSearchBar component (`app/Http/Livewire/MainSearchBar.php`) implements a sophisticated Elasticsearch-powered search system that searches across Users, Organizations, Banks, and Posts with advanced scoring, location-based prioritization, and intelligent result processing.
+
+## Search Flow Workflow
+
+### 1. Input Processing (`updatedSearch()`)
+- **Validation**: Minimum 2 characters required
+- **Sanitization**: Removes special characters, preserves alphanumeric and spaces
+- **Raw Term Storage**: Stores original search term for suggestion mapping
+
+### 2. Query Construction
+The search builds a complex BoolQuery with model-specific sub-queries:
+
+#### Profile Models (User, Organization, Bank)
+Each profile type gets its own BoolQuery with:
+- **Model filtering**: `__class_name` term query
+- **Field matching**: Multi-match across searchable fields
+- **Model-specific boost**: Applied at query level
+- **Location boosts**: Geographic proximity scoring
+
+#### Posts Model
+- **Publication filters**: Date-based visibility (from/till/deleted_at)
+- **Category filtering**: Configurable category inclusion
+- **Translation-aware**: Locale-specific field matching
+
+### 3. Field Configuration
+
+#### Profile Search Fields (`getProfileSearchFields()`)
+Fields searched with their boost factors from `config/timebank-cc.php`:
+- `cyclos_skills^1.5` - Skills from external system
+- `tags.contexts.tags.name_{locale}^2` - User-generated tags (highest boost)
+- `tags.contexts.categories.name_{locale}^1.4` - Tag categories
+- `motivation_{locale}^1` - Profile motivation
+- `about_short_{locale}^1` - Short description
+- `about_{locale}^1` - Full description
+- `name^1` - Profile name
+- `full_name^1` - Full profile name
+- `locations.{district|city|division|country}^1` - Location fields
+
+#### Post Search Fields (`getPostSearchFields()`)
+- `post_translations.title_{locale}^2` - Post title (highest boost)
+- `post_translations.content_{locale}^1` - Post content
+- `post_translations.excerpt_{locale}^1.5` - Post excerpt
+- `post_category.names.name_{locale}^2` - Category name
+
+## Result Prioritization System
+
+### 1. Model-Level Boosts (`config.timebank-cc.boosted_models`)
+- **Posts**: 4x boost (highest priority)
+- **Organizations**: 3x boost
+- **Banks**: 3x boost  
+- **Users**: 1x boost (baseline)
+
+### 2. Location Proximity Scoring (`calculateLocationProximity()`)
+Uses the active user's location hierarchy to score results:
+
+#### Proximity Levels (best to worst)
+1. **same_district**: 5.0x boost (1000 base score)
+2. **same_city**: 3.0x boost (800 base score)  
+3. **same_division**: 2.0x boost (600 base score)
+4. **same_country**: 1.5x boost (400 base score)
+5. **different_country**: 1.0x boost (200 base score)
+6. **no_location**: 0.9x boost (0 base score)
+
+#### Location Boost Application (`addLocationBoosts()`)
+For profile queries, adds additional SHOULD clauses for location matching:
+- District match: 5.0 boost
+- City match: 3.0 boost
+- Division match: 2.0 boost
+- Country match: 1.5 boost
+
+### 3. Composite Scoring (`processAndScoreResults()`)
+Final score calculation:
+```
+composite_score = location_base_score + (elasticsearch_score * 20)
+final_score = composite_score / 10
+```
+
+### 4. Search Optimization Helper
+Optional enhancement (`config.search_optimization.enabled`):
+- Profile verification boosts
+- Complete profile bonuses
+- Recent activity factors
+- Category matching multipliers
+
+## Highlighting and Suggestions
+
+### 1. Highlight Configuration
+- **Fragment size**: 80 characters
+- **Fragments per field**: 1-2 fragments
+- **Order**: By relevance score
+- **Tags**: Configurable HTML wrapping
+- **Field limiting**: Only content fields highlighted (location excluded)
+
+### 2. Highlight Priority (`limitHighlights()`)
+Returns single most relevant highlight in priority order:
+1. Profile name/full_name
+2. about_short/about fields
+3. Skills (cyclos_skills)
+4. Tags and categories
+5. Post titles/excerpts/content
+
+### 3. Suggestion Generation (`extractSuggestions()`)
+From highlights, extracts up to 5 suggestions:
+- Sentence-based extraction
+- Search term context preservation
+- 5-word maximum length
+- Duplicate removal
+
+## Display Processing (Search/Show Component)
+
+### 1. Result Caching (`showSearchResults()`)
+Results cached for 5 minutes (configurable) with:
+- Search term
+- Result references (model/id/highlight/score)
+- Total count
+- Cache key: `main_search_bar_results_{user_id}`
+
+### 2. Data Loading (`Search/Show.render()`)
+- **Eager loading**: Efficiently loads models by type
+- **Relationship optimization**: Loads required relations only
+- **Pagination**: 15 results per page (configurable)
+
+### 3. Card Processing
+
+#### Profile Cards
+- **Reaction data**: Star/bookmark/like counts via Laravel-Love
+- **Location display**: Short and full location strings
+- **Skills rendering**: Responsive skill tag display with overflow indicators
+- **Status indicators**: Online/away presence
+- **Profile filtering**: Inactive/incomplete/unverified profiles hidden
+
+#### Post Cards
+- **Media handling**: Hero image display
+- **Meeting info**: Date/venue/location extraction
+- **Category display**: Translated category names
+- **Publication status**: Date-based visibility enforcement
+
+### 4. Search Score Display
+- Normalized scores displayed to users
+- Score transparency for result ranking understanding
+
+## Configuration Impact
+
+### Key Config Sections (`config/timebank-cc.php`)
+
+#### `main_search_bar.boosted_fields`
+Controls field-level importance in matching
+
+#### `main_search_bar.boosted_models`  
+Sets model-type priority multipliers
+
+#### `main_search_bar.search`
+Elasticsearch query behavior and highlighting
+
+#### `search_optimization`
+Advanced scoring factors and location boosts
+
+#### Profile Filtering Settings
+- `profile_inactive.profile_search_hidden`
+- `profile_email_unverified.profile_search_hidden`  
+- `profile_incomplete.profile_search_hidden`
+
+## Performance Considerations
+
+### 1. Elasticsearch Optimizations
+- **Index selection**: Only searches relevant indices
+- **Query size limits**: Max 50 results (configurable)
+- **Highlight optimization**: Limited fragments and field selection
+
+### 2. Laravel Optimizations
+- **Eager loading**: Batch loads models with relationships
+- **Result caching**: 5-minute TTL with extension on access
+- **Location caching**: Hierarchy lookups cached when enabled
+
+### 3. Frontend Optimizations
+- **Pagination**: 15 items per page default
+- **Lazy loading**: Skills and media loaded as needed
+- **Cache warming**: Search extends cache TTL on result access
+
+## Search Analytics (Optional)
+
+When `search_optimization.analytics.enabled`:
+- Search pattern tracking
+- Location-based search metrics
+- Performance monitoring
+- Result relevance analytics
+
+This comprehensive search system balances relevance, performance, and user experience while providing rich, context-aware results with geographic and content-based prioritization.