timebank-cc-public/references/SEARCH_REFERENCE.md

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.