docs(README): update with new API features and architectural details

fulleni · fulleni · commit 4309be178d4f · 2025-05-02T19:00:54.000+01:00
- Add overview of User Settings API and its endpoints
- Refactor Core Functionality section with more detailed information
- Update Technical Overview with new shared packages and patterns
- Restructure API Endpoint documentation for clarity
- Improve consistency in error handling and response structure description
diff --git a/README.md b/README.md
@@ -1,61 +1,74 @@
 # ht_api
 
-<!-- Badges (Update coverage XX value after running tests) -->
 ![coverage: percentage](https://img.shields.io/badge/coverage-XX-green)
 [![style: very good analysis](https://img.shields.io/badge/style-very_good_analysis-B22C89.svg)](https://pub.dev/packages/very_good_analysis)
 [![License: PolyForm Free Trial](https://img.shields.io/badge/License-PolyForm%20Free%20Trial-blue)](https://polyformproject.org/licenses/free-trial/1.0.0)
 
 ## Overview
 
-`ht_api` is the backend API component of the Headlines Toolkit (HT) project. It serves as the central data provider for HT applications (like the mobile app and web dashboard), offering access to various data models required by the toolkit. Built with Dart using the Dart Frog framework, it prioritizes simplicity, maintainability, and scalability through a generic API design.
+`ht_api` is the central backend API service for the Headlines Toolkit (HT) project. Built with Dart using the Dart Frog framework, it provides essential APIs to support HT client applications (like the mobile app and web dashboard). It aims for simplicity, maintainability, and scalability, currently offering APIs for data access and user settings management.
 
 ## Features
 
-*   **Generic Data Endpoint (`/api/v1/data`):** Provides a unified RESTful interface for performing CRUD (Create, Read, Update, Delete) operations on multiple data models.
+### Core Functionality
+
+*   **Standardized Success Responses:** Returns consistent JSON success responses wrapped in a `SuccessApiResponse` structure, including request metadata (`requestId`, `timestamp`).
+*   **Standardized Error Handling:** Returns consistent JSON error responses via centralized middleware (`lib/src/middlewares/error_handler.dart`) for predictable client-side handling.
+*   **Request Traceability:** Generates a unique `requestId` (UUID v4) for each incoming request, included in success response metadata and available for server-side logging via context.
+*   **In-Memory Demo Mode:** Utilizes pre-loaded fixture data (`lib/src/fixtures/`) for demonstration and development purposes, simulating a live backend without external dependencies for core data and settings.
+
+### Data API (`/api/v1/data`)
+
+*   **Generic Data Endpoint:** Provides a unified RESTful interface for performing CRUD (Create, Read, Update, Delete) operations on multiple data models.
 *   **Model Agnostic Design:** Supports various data types through a single endpoint structure, determined by the `?model=` query parameter.
-*   **Currently Supported Models:**
+*   **Currently Supported Data Models:**
     *   `headline`
     *   `category`
     *   `source`
     *   `country`
-*   **Standardized Success Responses:** Returns consistent JSON success responses wrapped in a `SuccessApiResponse` structure, including request metadata (`requestId`, `timestamp`).
-*   **Standardized Error Handling:** Returns consistent JSON error responses via centralized middleware (`lib/src/middlewares/error_handler.dart`) for predictable client-side handling.
-*   **Request Traceability:** Generates a unique `requestId` (UUID v4) for each incoming request, included in success response metadata and available for server-side logging via context.
-*   **In-Memory Demo Mode:** Utilizes pre-loaded fixture data (`lib/src/fixtures/`) for demonstration and development purposes, simulating a live backend without external dependencies.
-*   **Standardized Error Handling:** Returns consistent JSON error responses via centralized middleware (`lib/src/middlewares/error_handler.dart`) for predictable client-side handling.
+
+### User Settings API (`/api/v1/users/me/settings`)
+
+*   **User-Specific Settings Management:** Provides RESTful endpoints for managing application settings (currently treated globally, future enhancement for user-specific).
+*   **Supported Settings:**
+    *   Display Settings (Theme, Font, etc.)
+    *   Language Preference
 
 ## Technical Overview
 
 *   **Language:** Dart (`>=3.0.0 <4.0.0`)
 *   **Framework:** Dart Frog (`^1.1.0`)
-*   **Architecture:** Layered architecture leveraging shared packages and a generic API pattern.
+*   **Architecture:** Layered architecture leveraging shared packages.
 *   **Key Packages & Shared Core:**
     *   `dart_frog`: The web framework foundation.
     *   `uuid`: Used to generate unique request IDs.
-    *   `ht_shared`: Contains shared data models (`Headline`, `Category`, `Source`, `Country`, `SuccessApiResponse`, `ResponseMetadata`, etc.) used across the HT ecosystem.
-    *   `ht_data_client`: Defines the generic `HtDataClient<T>` interface for data access operations.
-    *   `ht_data_inmemory`: Provides the `HtDataInMemoryClient<T>` implementation, used here for the demo mode, seeded with fixture data.
-    *   `ht_data_repository`: Defines the generic `HtDataRepository<T>` which abstracts the data client, providing a clean interface to the API route handlers.
-    *   `ht_http_client`: Provides custom HTTP exceptions (`HtHttpException` subtypes) used for consistent error signaling, even by the in-memory client.
+    *   `ht_shared`: Contains shared data models (`Headline`, `Category`, etc.), API response wrappers (`SuccessApiResponse`, `ResponseMetadata`), and standard exceptions (`HtHttpException`).
+    *   `ht_data_client`: Defines the generic `HtDataClient<T>` interface.
+    *   `ht_data_inmemory`: Provides the `HtDataInMemoryClient<T>` implementation for data.
+    *   `ht_data_repository`: Defines the generic `HtDataRepository<T>` for data access.
+    *   `ht_app_settings_client`: Defines the `HtAppSettingsClient` interface for settings.
+    *   `ht_app_settings_inmemory`: Provides the `HtAppSettingsInMemory` implementation for settings.
+    *   `ht_app_settings_repository`: Defines the `HtAppSettingsRepository` for settings management.
+    *   `ht_http_client`: Provides custom HTTP exceptions (`HtHttpException` subtypes) used for consistent error signaling.
 *   **Key Patterns:**
-    *   **Generic Repository Pattern:** `HtDataRepository<T>` provides a type-safe abstraction over data fetching logic. Route handlers interact with repositories, not directly with data clients.
-    *   **Generic Data Endpoint:** A single set of route handlers (`/api/v1/data/index.dart`, `/api/v1/data/[id].dart`) serves multiple data models.
-    *   **Model Registry:** A central map (`lib/src/registry/model_registry.dart`) links model name strings (from the `?model=` query parameter) to model-specific configurations (`ModelConfig`), primarily containing serialization functions (`fromJson`) and ID extraction logic (`getId`).
-    *   **Dependency Injection (Dart Frog Providers):** Middleware (`routes/_middleware.dart`) is used to instantiate and provide singleton instances of each `HtDataRepository<T>` (configured with the in-memory client and fixture data), the `ModelRegistryMap`, and a unique `RequestId` per request. Route-specific middleware (`routes/api/v1/data/_middleware.dart`) resolves the requested model, validates it, and provides the corresponding `ModelConfig` and model name string to the handler.
-    *   **Centralized Error Handling:** The `errorHandler` middleware intercepts exceptions (especially `HtHttpException` subtypes and `FormatException`) and maps them to standardized JSON error responses with appropriate HTTP status codes.
+    *   **Repository Pattern:** `HtDataRepository<T>` and `HtAppSettingsRepository` provide clean abstractions over data/settings logic. Route handlers interact with repositories.
+    *   **Generic Data Endpoint:** A single set of route handlers serves multiple data models via `/api/v1/data`.
+    *   **Model Registry:** A central map (`lib/src/registry/model_registry.dart`) links data model names to configurations (`ModelConfig`) for the generic data endpoint.
+    *   **Dependency Injection (Dart Frog Providers):** Middleware (`routes/_middleware.dart`) provides singleton instances of repositories (`HtDataRepository<T>`, `HtAppSettingsRepository`), the `ModelRegistryMap`, and a unique `RequestId`.
+    *   **Centralized Error Handling:** The `errorHandler` middleware intercepts exceptions and maps them to standardized JSON error responses.
 
-## API Endpoint: `/api/v1/data`
+## API Endpoints: Data (`/api/v1/data`)
 
 This endpoint serves as the single entry point for accessing different data models. The specific model is determined by the `model` query parameter.
 
 **Supported `model` values:** `headline`, `category`, `source`, `country`
 
-**Standard Response Structure:**
+**Standard Response Structure:** (Applies to both Data and Settings APIs)
 
 *   **Success:**
     ```json
     {
-      "data": <item_or_paginated_list>,
+      "data": <item_or_paginated_list_or_settings_object>,
       "metadata": {
         "request_id": "unique-uuid-v4-per-request",
         "timestamp": "iso-8601-utc-timestamp"
@@ -72,47 +85,84 @@ This endpoint serves as the single entry point for accessing different data mode
     }
     ```
 
-**Operations:**
+**Data Operations:**
 
 1.  **Get All Items (Collection)**
     *   **Method:** `GET`
     *   **Path:** `/api/v1/data?model=<model_name>`
-    *   **Optional Query Parameters:**
-        *   `limit=<int>`: Limit the number of items returned.
-        *   `startAfterId=<string>`: Paginate results, starting after the item with this ID.
-        *   *Other query parameters*: Passed directly to the repository's `readAllByQuery` method for filtering (e.g., `?model=headline&category=Technology`).
+    *   **Optional Query Parameters:** `limit=<int>`, `startAfterId=<string>`, other filtering params.
     *   **Success Response:** `200 OK` with `SuccessApiResponse<PaginatedResponse<T>>`.
     *   **Example:** `GET /api/v1/data?model=headline&limit=10`
 
 2.  **Create Item**
     *   **Method:** `POST`
     *   **Path:** `/api/v1/data?model=<model_name>`
-    *   **Request Body:** JSON object representing the item to create (ID is usually omitted if auto-generated).
+    *   **Request Body:** JSON object representing the item to create.
     *   **Success Response:** `201 Created` with `SuccessApiResponse<T>` containing the created item.
-    *   **Example:** `POST /api/v1/data?model=category` with body `{"name": "Sports", "description": "News about sports"}`
+    *   **Example:** `POST /api/v1/data?model=category` with body `{"name": "Sports", ...}`
 
 3.  **Get Item by ID**
     *   **Method:** `GET`
     *   **Path:** `/api/v1/data/<item_id>?model=<model_name>`
-    *   **Success Response:** `200 OK` with `SuccessApiResponse<T>` containing the requested item.
-    *   **Error Response:** `404 Not Found` if the ID doesn't exist for the given model.
+    *   **Success Response:** `200 OK` with `SuccessApiResponse<T>`.
+    *   **Error Response:** `404 Not Found`.
     *   **Example:** `GET /api/v1/data/some-headline-id?model=headline`
 
 4.  **Update Item by ID**
     *   **Method:** `PUT`
     *   **Path:** `/api/v1/data/<item_id>?model=<model_name>`
-    *   **Request Body:** JSON object representing the complete updated item (must include the correct `id`).
-    *   **Success Response:** `200 OK` with `SuccessApiResponse<T>` containing the updated item.
-    *   **Error Response:** `404 Not Found`, `400 Bad Request` (e.g., ID mismatch).
-    *   **Example:** `PUT /api/v1/data/some-category-id?model=category` with updated category JSON in the body.
+    *   **Request Body:** JSON object representing the complete updated item (must include `id`).
+    *   **Success Response:** `200 OK` with `SuccessApiResponse<T>`.
+    *   **Error Response:** `404 Not Found`, `400 Bad Request`.
+    *   **Example:** `PUT /api/v1/data/some-category-id?model=category` with updated category JSON.
 
 5.  **Delete Item by ID**
     *   **Method:** `DELETE`
     *   **Path:** `/api/v1/data/<item_id>?model=<model_name>`
-    *   **Success Response:** `204 No Content` (No body).
+    *   **Success Response:** `204 No Content`.
     *   **Error Response:** `404 Not Found`.
     *   **Example:** `DELETE /api/v1/data/some-source-id?model=source`
 
+## API Endpoints: User Settings (`/api/v1/users/me/settings`)
+
+These endpoints manage application settings. Currently, they operate on a global set of settings due to the lack of authentication; future enhancements will make them user-specific.
+
+**Standard Response Structure:** Uses the same `SuccessApiResponse` and error structure as the Data API.
+
+**Settings Operations:**
+
+1.  **Get Display Settings**
+    *   **Method:** `GET`
+    *   **Path:** `/api/v1/users/me/settings/display`
+    *   **Success Response:** `200 OK` with `SuccessApiResponse<DisplaySettings>`.
+    *   **Example:** `GET /api/v1/users/me/settings/display`
+
+2.  **Update Display Settings**
+    *   **Method:** `PUT`
+    *   **Path:** `/api/v1/users/me/settings/display`
+    *   **Request Body:** JSON object representing the complete `DisplaySettings`.
+    *   **Success Response:** `200 OK` with `SuccessApiResponse<DisplaySettings>` containing the updated settings.
+    *   **Example:** `PUT /api/v1/users/me/settings/display` with `DisplaySettings` JSON in the body.
+
+3.  **Get Language Setting**
+    *   **Method:** `GET`
+    *   **Path:** `/api/v1/users/me/settings/language`
+    *   **Success Response:** `200 OK` with `SuccessApiResponse<Map<String, String>>` (e.g., `{"data": {"language": "en"}, ...}`).
+    *   **Example:** `GET /api/v1/users/me/settings/language`
+
+4.  **Update Language Setting**
+    *   **Method:** `PUT`
+    *   **Path:** `/api/v1/users/me/settings/language`
+    *   **Request Body:** JSON object `{"language": "<code>"}` (e.g., `{"language": "es"}`).
+    *   **Success Response:** `200 OK` with `SuccessApiResponse<Map<String, String>>` containing the updated language setting.
+    *   **Example:** `PUT /api/v1/users/me/settings/language` with body `{"language": "fr"}`.
+
+5.  **Clear All Settings**
+    *   **Method:** `DELETE`
+    *   **Path:** `/api/v1/users/me/settings`
+    *   **Success Response:** `204 No Content`.
+    *   **Example:** `DELETE /api/v1/users/me/settings`
+
 ## Setup & Running
 
 1.  **Prerequisites:**
