feat(routes): implement request ID middleware for enhanced logging & debugging

- Add RequestId class to serve as a unique identifier for each HTTP request
- Integrate UUID package for generating version 4 UUIDs
- Implement middleware to generate and provide RequestId for each incoming request
- Document the purpose and usage of RequestId for improved traceability in logs

Author: fulleni

routes/_middleware.dart

@@ -1,3 +1,4 @@
+// routes/_middleware.dart
 //
 // ignore_for_file: avoid_slow_async_io, avoid_catches_without_on_clauses
 
@@ -10,6 +11,49 @@ import 'package:ht_api/src/registry/model_registry.dart';
 import 'package:ht_data_inmemory/ht_data_inmemory.dart';
 import 'package:ht_data_repository/ht_data_repository.dart';
 import 'package:ht_shared/ht_shared.dart';
+import 'package:uuid/uuid.dart'; // Import the uuid package
+
+// --- Request ID Wrapper ---
+
+/// {@template request_id}
+/// A wrapper class holding a unique identifier (UUID v4) generated for each
+/// incoming HTTP request.
+///
+/// **Purpose:**
+/// The primary role of this ID is **traceability for logging and debugging**.
+/// It allows developers to follow the entire lifecycle of a *single request*
+/// through various middleware, route handlers, repository calls, and potential
+/// external service interactions by searching logs for this specific ID.
+/// If an error occurs during a request, this ID provides a way to isolate all
+/// related log entries for that specific transaction, simplifying debugging.
+///
+/// **Scope:**
+/// - The ID is **transient** for the request itself; it exists only during the
+///   request-response cycle.
+/// - It is **not persisted** in the main application database alongside models
+///   like Headlines or Categories.
+/// - Its value lies in being included in **persistent logs**.
+///
+/// **Distinction from other IDs:**
+/// - **User ID:** Identifies the authenticated user making the request. Often
+///   logged alongside the `request_id` for user-specific debugging.
+/// - **Session ID:** Tracks a user's session across multiple requests.
+/// - **Correlation ID:** Often generated by the *client* and passed in headers
+///   to link related requests initiated by the client for a larger workflow.
+///
+/// **Implementation:**
+/// This class ensures type safety when providing and reading the request ID
+/// from the Dart Frog context using `context.provide<RequestId>` and
+/// `context.read<RequestId>()`. This prevents potential ambiguity if other raw
+/// strings were provided into the context.
+/// {@endtemplate}
+class RequestId {
+  /// {@macro request_id}
+  const RequestId(this.id);
+
+  /// The unique identifier string (UUID v4).
+  final String id;
+}
 
 // --- Helper Function to Load Fixtures ---
 // Note:
@@ -114,8 +158,22 @@ Handler middleware(Handler handler) {
   final sourceRepository = _createSourceRepository();
   final countryRepository = _createCountryRepository();
 
+  // Create a UUID generator instance
+  const uuid = Uuid();
+
   // Chain the providers and other middleware
   return handler
+      // --- Request ID Provider ---
+      // Generate a unique ID for each request and provide it via context.
+      // Using the RequestId wrapper ensures type safety for context reads.
+      .use((innerHandler) {
+        return (context) {
+          final requestIdValue = uuid.v4();
+          final requestId = RequestId(requestIdValue);
+          // Provide the RequestId instance to downstream handlers/middleware
+          return innerHandler(context.provide<RequestId>(() => requestId));
+        };
+      })
       // Provide the Model Registry Map
       .use(
         modelRegistryProvider,