Merge pull request #17 from flutter-news-app-full-source-code/sync-api-server-docs

Sync api server docs

Author: fulleni

src/content/docs/api-server/architecture/data-access-flow.mdx

@@ -40,7 +40,7 @@ This flow applies to requests for a collection of items.
     This crucial middleware uses the `ModelConfig` to determine the required permission for a `GET` collection request. It checks if the authenticated user has this permission. If not, a `403 Forbidden` error is thrown.
 
 6.  **Route Handler (`/routes/api/v1/data/index.dart`)**
-    The request finally reaches the handler. The handler uses the `DataOperationRegistry` to find the correct `readAll` function for the specified model and executes it, passing along any filter, sort, or pagination parameters.
+    The request finally reaches the handler. The handler uses the `DataOperationRegistry` to find the correct `readAll` function for the specified model and executes it. For the `country` model, if a `usage` filter is present, the request is delegated to the `CountryService` for specialized, non-paginated results; otherwise, it proceeds with standard pagination and sorting.
 
 7.  **Response**
     The handler wraps the data from the repository in a standard `SuccessApiResponse` and sends it back to the client.

src/content/docs/api-server/architecture/data-seeding-and-fixtures.mdx

@@ -13,7 +13,7 @@ The primary goal of this system is to **guarantee a consistent and predictable s
 
 This process is designed to be **lean and focused on system setup, not content population**. It handles two critical, one-time tasks:
 
-1.  **Ensuring Database Indexes:** It creates all necessary MongoDB indexes, including TTL (Time-To-Live) indexes for temporary data like verification codes and text indexes for search functionality.
+1.  **Ensuring Database Indexes:** It creates all necessary MongoDB indexes, including TTL (Time-To-Live) indexes for temporary data like verification codes, text indexes for search functionality, and compound indexes to optimize country-related aggregation queries.
 2.  **Initializing the Admin User:** It securely sets up the single administrator account based on the `OVERRIDE_ADMIN_EMAIL` environment variable.
 
 ### Idempotent and Safe to Run

src/content/docs/api-server/features/data-management-api.mdx

@@ -23,6 +23,18 @@ GET /api/v1/data?model=headline
 GET /api/v1/data/some-topic-id?model=topic
 ```
 
+**Example: Fetching countries by usage**
+```http
+GET /api/v1/data?model=country&filter={"usage":"eventCountry"}
+```
+This fetches countries that are referenced as 'event countries' in headlines. Similarly, `filter={"usage":"headquarters"}` can be used to fetch countries that are headquarters for sources.
+
+<Aside type="note" title="Why use the 'usage' filter for countries?">
+The `usage` filter for the `country` model is designed to enhance the client-side user experience and optimize data retrieval. Instead of fetching a comprehensive list of all countries globally, this filter allows client applications to retrieve only those countries that are *relevant* to existing content.
+
+For instance, when a user wants to filter headlines by the country where the news event occurred, it's often more practical to present a list of countries for which actual headlines exist. Similarly, when filtering by the headquarters of news sources, displaying only countries that host active sources provides a more focused and actionable selection. This approach avoids presenting users with a long list of irrelevant options, streamlining navigation and improving the efficiency of data display.
+</Aside>
+
 ### The Dual Registry System
 
 The power behind this generic endpoint comes from two central registries:
@@ -41,7 +53,7 @@ The generic data endpoint can manage the following models out-of-the-box:
 -   `headline`
 -   `topic`
 -   `source`
--   `country`
+-   `country` (supports specialized filtering by `usage` for 'eventCountry' or 'headquarters')
 -   `language`
 -   `user`
 -   `user_app_settings`

src/content/docs/api-server/reference/data-access.mdx

@@ -23,7 +23,7 @@ The following model names are supported:
 -   `headline`
 -   `topic`
 -   `source`
--   `country`
+-   `country` (supports specialized filtering by `usage` for 'eventCountry' or 'headquarters')
 -   `language`
 -   `user`
 -   `user_app_settings`
@@ -32,7 +32,7 @@ The following model names are supported:
 -   `dashboard_summary`
 
 <Aside type="caution" title="Read-Only Models">
-The `country` and `language` models are configured to be **read-only** through the API (i.e., they do not support `POST`, `PUT`, or `DELETE` requests). This is an intentional design choice, as this foundational data is managed via the database seeding process.
+The `country` and `language` models are configured to be **read-only** through the API (i.e., they do not support `POST`, `PUT`, or `DELETE` requests). This is an intentional design choice. This foundational data is managed via the database seeding process.
 </Aside>
 
 <Aside type="caution">
@@ -51,6 +51,14 @@ Retrieves a paginated list of items for a specific model.
 #### Query Parameters
 
 -   **`filter`** (string, optional): A URL-encoded JSON string representing a MongoDB-style query.
+    <Aside type="note" title="Special Filter for Country Model: 'usage'">
+    For the `country` model, the `filter` parameter supports a special `usage` key. This allows you to retrieve a curated list of countries that are relevant to existing content, rather than all countries globally. This is particularly useful for populating dynamic dropdowns or filters in client applications.
+
+    -   `filter={"usage":"eventCountry"}`: Returns countries referenced as `eventCountry` in headlines.
+    -   `filter={"usage":"headquarters"}`: Returns countries referenced as `headquarters` in sources.
+
+    When using the `usage` filter for the `country` model, the response will **not** be paginated and will return the complete filtered set of countries.
+    </Aside>
 -   **`sort`** (string, optional): A comma-separated list of fields to sort by (e.g., `createdAt:desc,title:asc`).
 -   **`limit`** (integer, optional): The maximum number of items to return.
 -   **`cursor`** (string, optional): The pagination cursor from a previous response to fetch the next page.
@@ -74,6 +82,13 @@ GET /api/v1/data?model=headline&filter={"topic.id":{"$in":["topicId1","topicId2"
 ```
 This fetches headlines belonging to specific topics, sorted by creation date.
 </TabItem>
+<TabItem label="Country Usage Filter">
+**Request:**
+```
+GET /api/v1/data?model=country&filter={"usage":"eventCountry"}
+```
+This fetches all countries that are referenced as 'event countries' in headlines.
+</TabItem>
 </Tabs>
 
 -   **Success Response:**