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

Sync api docs

Author: fulleni

astro.config.mjs

@@ -63,9 +63,10 @@ export default defineConfig({
 							items: [
 								{ label: 'Overview', link: '/api-server/architecture/' },
 								{ label: 'Dependency Injection', link: '/api-server/architecture/dependency-injection' },
-								{ label: 'Middleware', link: '/api-server/architecture/middleware' },
-								{ label: 'Data Seeding & Fixtures', link: '/api-server/architecture/data-seeding-and-fixtures' },
-								{ label: 'Generic Data Endpoint', link: '/api-server/architecture/generic-data-endpoint' },
+								{ label: 'Middleware & Request Lifecycle', link: '/api-server/architecture/middleware' },
+								{ label: 'Generic Data Endpoint & Registries', link: '/api-server/architecture/generic-data-endpoint' },
+								{ label: 'Deep Dive: Data Access Flow', link: '/api-server/architecture/data-access-flow' },
+								{ label: 'Data Seeding & System Initialization', link: '/api-server/architecture/data-seeding-and-fixtures' },
 								{ label: 'Error Handling', link: '/api-server/architecture/error-handling' },
 							],
 						},

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

@@ -0,0 +1,80 @@
+---
+title: 'Architectural Deep Dive: Data Access Flow'
+description: A detailed walkthrough of how the API server processes a generic data request from start to finish.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+This document provides a comprehensive, step-by-step explanation of the entire request lifecycle for the generic data endpoint (`/api/v1/data`). Understanding this flow is key to appreciating the server's robust, maintainable, and extensible design.
+
+The architecture relies on a series of middleware and two central registries working in concert to process requests securely and efficiently.
+
+### Core Components
+
+-   **`ModelRegistry`**: A map that links a model's string name (e.g., `"headline"`) to a `ModelConfig` object. This config holds metadata for authorization rules and type-specific functions (`fromJson`, `getOwnerId`). It answers the question: **"What are the rules for this model?"**
+
+-   **`DataOperationRegistry`**: A map that links a model's string name to the actual functions that perform CRUD operations (e.g., `create`, `read`, `update`, `delete`). It answers the question: **"How do I perform this action for this model?"**
+
+-   **Middleware**: A chain of functions that process the request sequentially. Each middleware has a specific responsibility, such as authentication, authorization, or data fetching.
+
+---
+
+### Request Lifecycle for a Collection (`GET /api/v1/data?model=...`)
+
+This flow applies to requests for a collection of items.
+
+<Steps>
+1.  **Authentication (`authenticationProvider`)**
+    The first middleware validates the `Bearer` token and injects the `User` object into the request context. If the token is invalid, the user is considered unauthenticated.
+
+2.  **Enforce Authentication (`requireAuthentication`)**
+    This middleware checks if a `User` object is present in the context. Since the `/data` endpoint is protected, it will throw an `UnauthorizedException` if the user is not authenticated, aborting the request.
+
+3.  **Rate Limiting (`_dataRateLimiterMiddleware`)**
+    The user's request count is checked. If the limit is exceeded, the request is aborted with a `429 Too Many Requests` error. Admins and publishers bypass this check.
+
+4.  **Model Validation (`_modelValidationAndProviderMiddleware`)**
+    The `?model=` query parameter is read and validated against the `ModelRegistry`. If the model is valid, its `ModelConfig` is fetched and injected into the context for later use. If not, a `400 Bad Request` is thrown.
+
+5.  **Authorization (`authorizationMiddleware`)**
+    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.
+
+7.  **Response**
+    The handler wraps the data from the repository in a standard `SuccessApiResponse` and sends it back to the client.
+</Steps>
+
+---
+
+### Request Lifecycle for a Single Item (`GET /api/v1/data/[id]?model=...`)
+
+This flow is more complex, involving additional middleware to handle fetching and ownership checks.
+
+<Steps>
+1.  **Authentication, Rate Limiting, Model Validation, and Authorization**
+    The first five steps are identical to the collection request lifecycle. The `authorizationMiddleware` checks the `getItemPermission` from the `ModelConfig`.
+
+2.  **Data Fetching (`dataFetchMiddleware`)**
+    This is the first item-specific middleware. It reads the item `id` from the URL and uses the `DataOperationRegistry` to find and execute the correct `read` function for the model.
+    -   If the item is not found, it throws a `NotFoundException`.
+    -   If found, it wraps the item in a `FetchedItem` object and injects it into the context.
+
+3.  **Ownership Check (`ownershipCheckMiddleware`)**
+    This middleware inspects the `ModelConfig`. If the action requires an ownership check (`requiresOwnershipCheck: true`) and the user is not an admin, it:
+    -   Reads the pre-fetched item from the context.
+    -   Uses the `getOwnerId` function from the `ModelConfig` to get the item's owner ID.
+    -   Compares the owner ID to the authenticated user's ID.
+    -   If they don't match, it throws a `403 Forbidden` error.
+
+4.  **Route Handler (`/routes/api/v1/data/[id]/index.dart`)**
+    The request reaches the final handler. Because of the preceding middleware, the handler can safely assume the item exists and the user is authorized to access it. It simply reads the `FetchedItem` from the context and prepares the success response.
+
+5.  **Response**
+    The handler wraps the pre-fetched item in a `SuccessApiResponse` and sends it to the client.
+</Steps>
+
+<Aside type="note" title="PUT and DELETE Requests">
+The flow for `PUT` and `DELETE` requests is identical to the single item `GET` request. The only difference is that the `authorizationMiddleware` checks the `putPermission` or `deletePermission` from the `ModelConfig`, and the final route handler calls the appropriate `update` or `delete` function from the `DataOperationRegistry`.
+</Aside>

src/content/docs/api-server/architecture/error-handling.mdx

@@ -27,7 +27,7 @@ The following table lists the most common error codes and their corresponding HT
 
 | HTTP Status | Error Code             | Description                                                                                             |
 | :---------- | :--------------------- | :------------------------------------------------------------------------------------------------------ |
-| `400`       | `badRequest`           | The request was malformed, such as having invalid JSON or incorrect parameter formats.                  |
+| `400`       | `badRequest`           | The request was malformed. This can be due to invalid JSON in the body, or incorrect parameter formats (e.g., an invalid `filter` or `sort` query). |
 | `400`       | `invalidInput`         | A specific field in the request body or query parameter was invalid or missing.                         |
 | `401`       | `unauthorized`         | Authentication is required, but the request lacks a valid Bearer token. This can also mean the token is expired or has been invalidated (e.g., after sign-out). |
 | `401`       | `authenticationFailed` | The provided credentials (e.g., verification code) are incorrect.                                       |

src/content/docs/api-server/architecture/generic-data-endpoint.mdx

@@ -1,52 +1,38 @@
 ---
-title: Generic Data Endpoint
-description: Understand the powerful generic data endpoint and model registry pattern used in the API server.
+title: 'Pattern: Generic Data Endpoint & Registries'
+description: Understand the powerful generic data endpoint and registry patterns used in the API server.
 ---
 
 import { Aside } from '@astrojs/starlight/components';
 
-A significant architectural pattern in the API server is the use of a generic data endpoint powered by a `model_registry`. This design provides a single, consistent, and powerful interface for all standard CRUD (Create, Read, Update, Delete) operations, reducing code duplication and simplifying both the backend and client-side implementations.
+A significant architectural pattern in the API server is the use of a generic data endpoint powered by two central registries. This design provides a single, consistent, and powerful interface for all standard CRUD (Create, Read, Update, Delete) operations, reducing code duplication and simplifying both the backend and client-side implementations.
 
 ### The Challenge: Avoiding Boilerplate
 
-A typical REST API might have separate endpoints for each data type:
--   `/api/v1/headlines`
--   `/api/v1/topics`
--   `/api/v1/sources`
--   ...and so on.
+A typical REST API might have separate endpoints for each data type: `/headlines`, `/topics`, `/sources`, etc. This approach leads to a lot of boilerplate code, as the logic for handling GET, POST, PUT, and DELETE requests is often very similar for each model.
 
-While clear, this approach leads to a lot of boilerplate code, as the logic for handling GET, POST, PUT, and DELETE requests is often very similar for each model.
+### The Solution: A Single Endpoint with Registries
 
-### The Solution: A Single Endpoint with a Model Registry
-
-This API server solves the problem by using a single, dynamic endpoint:
-
-```
-/api/v1/data
-```
-
-This endpoint handles requests for **all** standard data models. The specific model to be acted upon is determined by a `?model=` query parameter.
+This API server solves the problem by using a single, dynamic endpoint: `/api/v1/data`. This endpoint handles requests for all standard data models, with the specific model determined by a `?model=` query parameter.
 
 -   `GET /api/v1/data?model=headline` -> Returns a list of headlines.
--   `GET /api/v1/data/some-id?model=topic` -> Returns a single topic.
 -   `POST /api/v1/data?model=source` -> Creates a new source.
 
-### The `model_registry`
+This is made possible by two key components:
 
-The magic behind this is the `model_registry`, a map defined in `lib/src/registry/model_registry.dart`. This registry links the string name of a model (e.g., "headline") to a `ModelConfig` object.
+1.  **`ModelRegistry`**: This registry maps a model name (e.g., `"headline"`) to a `ModelConfig` object. The config defines the **rules** for the model, such as authorization requirements and type-specific functions (`fromJson`, `getOwnerId`).
 
-Each `ModelConfig` contains:
--   **Type-Specific Functions:** Functions like `fromJson` to deserialize the data correctly.
--   **Authorization Rules:** A detailed permission configuration for each HTTP method (GET, POST, PUT, DELETE), specifying what roles or permissions are required for that action.
+2.  **`DataOperationRegistry`**: This registry maps a model name to the actual **functions** that perform the CRUD operations (e.g., the function to fetch all headlines, the function to create a new source).
 
-When a request comes in, the server's middleware looks up the `model` parameter in the registry, retrieves the correct configuration, and uses it to:
-1.  Authorize the request based on the user's role and the action's permission requirements.
-2.  Forward the request to the correct generic `DataRepository`.
-3.  Deserialize and serialize data using the correct model class.
+When a request comes in, middleware uses the `ModelRegistry` to authorize the request and the route handlers use the `DataOperationRegistry` to execute the correct data operation.
 
 <Aside type="note" title="Architectural Benefits">
--   **DRY (Don't Repeat Yourself):** Eliminates redundant route handlers for CRUD operations.
+-   **DRY (Don't Repeat Yourself):** Eliminates redundant route handlers.
 -   **Consistency:** Provides a uniform API for all data models.
--   **Extensibility:** Adding CRUD support for a new data model is as simple as adding a new entry to the `model_registry`.
--   **Centralized Authorization:** Security rules for data access are defined in one central, easy-to-audit location.
+-   **Extensibility:** Adding CRUD support for a new model is as simple as adding entries to the two registries.
+-   **Centralized Logic:** Authorization rules and data operations are defined in central, easy-to-audit locations.
+</Aside>
+
+<Aside type="tip">
+For a complete, step-by-step walkthrough of how the endpoint, registries, and middleware work together, see the [**Architectural Deep Dive: Data Access Flow**](./data-access-flow) guide.
 </Aside>

src/content/docs/api-server/architecture/middleware.mdx

@@ -1,37 +1,38 @@
 ---
-title: 'Advanced: Middleware'
-description: An explanation of the API server's middleware architecture and request lifecycle.
+title: 'Advanced: Middleware & Request Lifecycle'
+description: An explanation of the API server's middleware architecture and the detailed request lifecycle for different endpoints.
 ---
 
-import { Steps, Aside } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
 
 The API server uses a layered middleware architecture to handle requests. Middleware are functions that process a request before it reaches its final destination (the route handler). This approach allows for the separation of concerns like logging, authentication, and error handling from the core business logic.
 
-## Request Lifecycle
+An incoming request flows through a series of middleware in an "onion-skin" fashion. The outermost middleware runs first, and the innermost middleware runs last, just before the route handler.
 
-An incoming request to the API server flows through a series of middleware in an "onion-skin" fashion. The outermost middleware runs first, and the innermost middleware runs last, just before the route handler.
+### The Middleware Chain
 
-Here is the typical execution order for a request to a protected data endpoint like `/api/v1/data?model=headline`:
+The server defines middleware at different levels of the route tree. Here’s a breakdown of the key middleware and where they are applied:
 
-<Steps>
-1.  **Root Middleware (`/routes/_middleware.dart`)**
-    -   **Dependency Injection:** Initializes and provides all application-wide dependencies (repositories, services, etc.) into the request context. This happens once per request.
-    -   **Request ID Generation:** Assigns a unique ID to the request for logging and traceability.
-    -   **Request Logger:** Logs the incoming request details.
-    -   **Error Handler:** This is the outermost layer, wrapping the entire request to catch any exceptions thrown by inner layers and format them into a standardized JSON error response.
+-   **Root Middleware (`/routes/_middleware.dart`)**:
+    -   `errorHandler`: The final safety net that catches all exceptions and formats them into standard JSON error responses.
+    -   `requestLogger`: Logs details of every incoming request.
+    -   `requestIdProvider`: Assigns a unique ID to each request for tracing.
+    -   `dependencyProvider`: Initializes and injects all application-wide dependencies (repositories, services, registries) into the request context.
 
-2.  **API v1 Middleware (`/routes/api/v1/_middleware.dart`)**
-    -   **CORS Handling:** Applies Cross-Origin Resource Sharing (CORS) headers to the response, allowing the web dashboard to communicate with the API.
-    -   **Authentication Provider:** Checks for a `Bearer` token in the `Authorization` header. If present, it validates the token and injects the corresponding `User` object (or `null`) into the request context.
+-   **API v1 Middleware (`/routes/api/v1/_middleware.dart`)**:
+    -   `corsHeaders`: Applies Cross-Origin Resource Sharing (CORS) headers to responses.
+    -   `authenticationProvider`: Validates the `Bearer` token and injects a `User` object (or `null`) into the context.
 
-3.  **Data Route Middleware (`/routes/api/v1/data/_middleware.dart`)**
-    -   **Require Authentication:** Checks if a `User` object exists in the context. If not, it immediately aborts the request with a `401 Unauthorized` error.
-    -   **Rate Limiting:** If the user is not an admin or a publisher, it applies a rate limit based on the user's ID. If the limit is exceeded, it aborts with a `429 Too Many Requests` error.
-    -   **Model Validation:** Validates the `?model=` query parameter and injects the corresponding `ModelConfig` into the context.
-    -   **Authorization:** Checks if the authenticated user has the required permissions to perform the requested action on the specified model. If not, it aborts with a `403 Forbidden` error.
+-   **Data Route Group Middleware (`/routes/api/v1/data/_middleware.dart`)**:
+    -   `requireAuthentication`: Aborts the request if no authenticated user is found.
+    -   `_dataRateLimiterMiddleware`: Applies rate limiting based on the user's ID.
+    -   `_modelValidationAndProviderMiddleware`: Validates the `?model=` query parameter and injects the `ModelConfig` and model name into the context.
+    -   `authorizationMiddleware`: Performs high-level permission checks based on the `ModelConfig`.
 
-4.  **Route Handler (`/routes/api/v1/data/index.dart` or `[id].dart`)**
-    -   Finally, if all middleware checks pass, the request reaches the route handler, which contains the core business logic for the endpoint (e.g., fetching data from a repository and returning it).
-</Steps>
+-   **Item-Specific Middleware (`/routes/api/v1/data/[id]/_middleware.dart`)**:
+    -   `dataFetchMiddleware`: Fetches the specific item by its ID and injects it into the context.
+    -   `ownershipCheckMiddleware`: Verifies if the authenticated user is the owner of the fetched item, if required by the `ModelConfig`.
 
-This layered approach ensures that by the time a request reaches its route handler, it has been logged, authenticated, authorized, and has all necessary dependencies available via the request context.
+<Aside type="note">
+For a complete, step-by-step walkthrough of how these middleware interact with the data registries, see the [**Architectural Deep Dive: Data Access Flow**](./data-access-flow) guide.
+</Aside>