From e2e2f4eb46b873cbc9834d7287d7299c2807b827 Mon Sep 17 00:00:00 2001
From: fulleni <fulleni@hotmail.com>
Date: Fri, 22 Aug 2025 09:27:08 +0100
Subject: [PATCH 1/2] feat(country): implement search by name or usage

- Add support for searching countries by name or usage
- Update filter logic to use a case-insensitive regex
- Rename filter parameter from 'name' to 'q' for broader query support
---
 lib/src/services/country_service.dart | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/src/services/country_service.dart b/lib/src/services/country_service.dart
index 2cb4c79..8ac0527 100644
--- a/lib/src/services/country_service.dart
+++ b/lib/src/services/country_service.dart
@@ -73,12 +73,12 @@ class CountryService {
     _log.info('Fetching countries with filter: $filter');
 
     final usage = filter?['usage'] as String?;
-    final name = filter?['name'] as String?;
+    final q = filter?['q'] as String?; 
 
     Map<String, dynamic>? nameFilter;
-    if (name != null && name.isNotEmpty) {
+    if (q != null && q.isNotEmpty) {
       // Create a case-insensitive regex filter for the name.
-      nameFilter = {r'$regex': name, r'$options': 'i'};
+      nameFilter = {r'$regex': q, r'$options': 'i'};
     }
 
     if (usage == null || usage.isEmpty) {

From 8346a301636b45701a78a57282c09133275bca60 Mon Sep 17 00:00:00 2001
From: fulleni <fulleni@hotmail.com>
Date: Fri, 22 Aug 2025 09:27:20 +0100
Subject: [PATCH 2/2] refactor(database): add detailed comments for index
 creations

- Add comprehensive comments describing the purpose and functionality of each index
- Introduce new indexes for improved search and filtering capabilities
- Enhance code readability and maintainability by providing context for index usage
---
 .../services/database_seeding_service.dart    | 31 ++++++++++++++++---
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/lib/src/services/database_seeding_service.dart b/lib/src/services/database_seeding_service.dart
index 26007f1..489d179 100644
--- a/lib/src/services/database_seeding_service.dart
+++ b/lib/src/services/database_seeding_service.dart
@@ -103,33 +103,54 @@ class DatabaseSeedingService {
   Future<void> _ensureIndexes() async {
     _log.info('Ensuring database indexes exist...');
     try {
-      // Text index for searching headlines by title
+      /// Text index for searching headlines by title.
+      /// This index supports efficient full-text search queries on the 'title' field
+      /// of headline documents, crucial for the main search functionality.
       await _db
           .collection('headlines')
           .createIndex(keys: {'title': 'text'}, name: 'headlines_text_index');
 
-      // Text index for searching topics by name
+      /// Text index for searching topics by name.
+      /// This index enables efficient full-text search on the 'name' field of
+      /// topic documents, used for searching topics.
       await _db
           .collection('topics')
           .createIndex(keys: {'name': 'text'}, name: 'topics_text_index');
 
-      // Text index for searching sources by name
+      /// Text index for searching sources by name.
+      /// This index facilitates efficient full-text search on the 'name' field of
+      /// source documents, used for searching sources.
       await _db
           .collection('sources')
           .createIndex(keys: {'name': 'text'}, name: 'sources_text_index');
 
-      // Index for searching countries by name (case-insensitive friendly)
+      /// Index for searching countries by name.
+      /// This index supports efficient queries and sorting on the 'name' field
+      /// of country documents, particularly for direct country searches.
       await _db
           .collection('countries')
           .createIndex(keys: {'name': 1}, name: 'countries_name_index');
 
-      // Indexes for country aggregation queries
+      /// Indexes for country aggregation queries.
+      /// This compound index optimizes queries that filter by 'status' and
+      /// group by 'eventCountry.id' in the headlines collection.
       await _db
           .collection('headlines')
           .createIndex(
             keys: {'status': 1, 'eventCountry.id': 1},
             name: 'status_eventCountry_index',
           );
+      /// Index for efficient filtering of headlines by the name of the
+      /// associated event country. This is crucial for the country search
+      /// functionality when filtering by 'eventCountry' usage.
+      await _db
+          .collection('headlines')
+          .createIndex(
+            keys: {'eventCountry.name': 1},
+            name: 'eventCountry_name_index',
+          );
+      /// This compound index optimizes queries that filter by 'status' and
+      /// group by 'headquarters.id' in the sources collection.
       await _db
           .collection('sources')
           .createIndex(