docs: clarify authentication middleware flow

- Updated middleware descriptions
- Explained authentication flow
- Clarified request context usage

Author: fulleni

routes/api/v1/_middleware.dart

@@ -2,8 +2,20 @@ import 'package:dart_frog/dart_frog.dart';
 import 'package:ht_api/src/middlewares/authentication_middleware.dart';
 
 Handler middleware(Handler handler) {
-  // This middleware applies authentication to all routes under /api/v1/.
-  // It expects AuthTokenService to be provided by an ancestor middleware
-  // (e.g., the global routes/_middleware.dart).
+  // This middleware applies the `authenticationProvider` to all routes
+  // under /api/v1/.
+  //
+  // The `authenticationProvider()` (from `lib/src/middlewares/authentication_middleware.dart`):
+  // 1. Attempts to extract a Bearer token from the 'Authorization' header.
+  // 2. Validates the token using the `AuthTokenService` (which must be
+  //    provided by an ancestor middleware, e.g., `routes/_middleware.dart`).
+  // 3. Provides the resulting `User?` (nullable User object) into the request
+  //    context. This makes `context.read<User?>()` available downstream.
+  //
+  // IMPORTANT: `authenticationProvider()` itself does NOT block unauthenticated
+  // requests. It simply makes the user's identity available if authentication
+  // is successful. Stricter access control (blocking unauthenticated users)
+  // is handled by `requireAuthentication()` middleware applied in more specific
+  // route groups (e.g., `/api/v1/data/_middleware.dart`).
   return handler.use(authenticationProvider());
 }

routes/api/v1/data/_middleware.dart

@@ -63,12 +63,32 @@ Middleware _modelValidationAndProviderMiddleware() {
 // Main middleware exported for the /api/v1/data route group.
 Handler middleware(Handler handler) {
   // This 'handler' is the actual route handler from index.dart or [id].dart.
-  // The .use() method applies middleware in an "onion-skin" fashion.
-  // The last .use() is the outermost layer.
-  // So, requireAuthentication() runs first. If it passes,
-  // _modelValidationAndProviderMiddleware() runs next.
-  // If that passes, the actual route handler is executed.
+  //
+  // The .use() method applies middleware in an "onion-skin" fashion, where
+  // the last .use() call in the chain represents the outermost middleware layer.
+  // Therefore, the execution order for an incoming request is:
+  //
+  // 1. `requireAuthentication()`:
+  //    - This runs first. It relies on `authenticationProvider()` (from the
+  //      parent `/api/v1/_middleware.dart`) having already attempted to
+  //      authenticate the user and provide `User?` into the context.
+  //    - If `User` is null (no valid authentication), `requireAuthentication()`
+  //      throws an `UnauthorizedException`, and the request is aborted (usually
+  //      resulting in a 401 response via the global `errorHandler`).
+  //    - If `User` is present, the request proceeds to the next middleware.
+  //
+  // 2. `_modelValidationAndProviderMiddleware()`:
+  //    - This runs if `requireAuthentication()` passes.
+  //    - It validates the `?model=` query parameter and provides the
+  //      `ModelConfig` and `modelName` into the context.
+  //    - If model validation fails, it returns a 400 Bad Request response directly.
+  //    - If successful, it calls the next handler in the chain.
+  //
+  // 3. Actual Route Handler (from `index.dart` or `[id].dart`):
+  //    - This runs last, only if both preceding middlewares pass. It will have
+  //      access to a non-null `User`, `ModelConfig`, and `modelName` from the context.
+  //
   return handler
-      .use(_modelValidationAndProviderMiddleware())
-      .use(requireAuthentication());
+      .use(_modelValidationAndProviderMiddleware()) // Applied second (inner)
+      .use(requireAuthentication()); // Applied first (outermost)
 }

routes/api/v1/users/[userId]/settings/_middleware.dart

@@ -5,7 +5,23 @@ import 'package:dart_frog/dart_frog.dart';
 import 'package:ht_api/src/middlewares/authentication_middleware.dart';
 
 Handler middleware(Handler handler) {
-  // Apply requireAuthentication to protect all settings routes.
-  // This ensures that context.read<User>() will be non-null in these handlers.
+  // Apply `requireAuthentication()` to protect all settings routes within the
+  // /api/v1/users/[userId]/settings/ path.
+  //
+  // This middleware relies on `authenticationProvider()` (applied in the parent
+  // `/api/v1/_middleware.dart`) to have already:
+  // 1. Attempted to authenticate the user from a Bearer token.
+  // 2. Provided `User?` (nullable User) into the request context.
+  //
+  // `requireAuthentication()` then checks this `User?` from the context:
+  // - If `User` is null (meaning no valid authentication was established by
+  //   `authenticationProvider`), it throws an `UnauthorizedException`.
+  //   This typically results in a 401 HTTP response via the global `errorHandler`.
+  // - If `User` is present (not null), the request is allowed to proceed to the
+  //   actual route handler (e.g., display.dart, language.dart).
+  //
+  // This ensures that all settings endpoints are strictly accessible only by
+  // authenticated users, and `context.read<User>()` (non-nullable) can be
+  // safely used within these route handlers.
   return handler.use(requireAuthentication());
 }