docs: initial content for Flutter News App documentation

- Added overview pages for API endpoints and deployment guides
- Included local setup instructions for API server, web dashboard, and mobile client
- Covered web dashboard features including authentication, content management, and app configuration
- Provided API reference for data endpoints

Author: fulleni

src/content/docs/advanced/dependency-injection.mdx

@@ -0,0 +1,48 @@
+---
+title: 'Advanced: Dependency Injection'
+description: An explanation of the API server's service layer and dependency injection pattern.
+---
+
+import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The API server is built with a clean, layered architecture that separates concerns and promotes testability. At the heart of this design is the use of a service layer and a centralized dependency injection (DI) mechanism.
+
+## The `AppDependencies` Singleton
+
+The `AppDependencies` class (`lib/src/config/app_dependencies.dart`) is a singleton responsible for initializing and providing access to all major application-wide dependencies.
+
+When the server first starts, the `init()` method on this singleton is called. It performs several critical setup tasks in order:
+
+1.  **Initializes the Database Connection:** Establishes a connection to the MongoDB instance specified in the environment variables.
+2.  **Seeds the Database:** Runs a seeding service to populate the database with initial data (countries, topics, etc.) if it doesn't already exist.
+3.  **Initializes Data Clients:** Creates instances of the `DataMongodb` clients for each data model. These clients are the lowest-level components that directly interact with the database.
+4.  **Initializes Repositories:** Wraps each data client in a `DataRepository`. Repositories provide a clean abstraction layer over the data clients.
+5.  **Initializes Services:** Creates instances of all core business logic services (e.g., `AuthService`, `DashboardSummaryService`), injecting the repositories and other services they depend on.
+
+<Aside type="info">
+This centralized initialization ensures that all dependencies are ready before the server begins accepting requests and that the dependency graph is correctly resolved.
+</Aside>
+
+## Dependency Injection in Requests
+
+Once initialized, these dependencies are made available to every incoming request using Dart Frog's middleware and provider system.
+
+The root middleware (`/routes/_middleware.dart`) is responsible for this. For each request, it:
+
+1.  Ensures `AppDependencies.instance.init()` has been called.
+2.  Uses a series of `.use(provider<T>((_) => deps.dependency))` calls to inject each repository and service from the `AppDependencies` singleton into the request context.
+
+### Accessing Dependencies in Route Handlers
+
+Because of this DI setup, any route handler or downstream middleware can easily access a required dependency by calling `context.read<T>()`.
+
+**Example:**
+```dart title="A route handler"
+// Read the AuthService provided by the root middleware
+final authService = context.read<AuthService>();
+
+// Now you can use the service
+final result = await authService.performAnonymousSignIn();
+```
+
+This pattern decouples the route handlers from the concrete implementation of the services they use, making the code cleaner, more modular, and significantly easier to test.

src/content/docs/advanced/middleware.mdx

@@ -0,0 +1,36 @@
+---
+title: 'Advanced: Middleware'
+description: An explanation of the API server's middleware architecture and request lifecycle.
+---
+
+import { Steps, 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 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.
+
+Here is the typical execution order for a request to a protected data endpoint like `/api/v1/data?model=headline`:
+
+<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.
+
+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.
+
+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.
+    -   **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.
+
+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>
+
+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.

src/content/docs/advanced/rbac.mdx

@@ -0,0 +1,54 @@
+---
+title: 'Advanced: Role-Based Access Control (RBAC)'
+description: An explanation of the API server's permission and role system.
+---
+
+import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The API server implements a robust Role-Based Access Control (RBAC) system to secure its endpoints and data. This system ensures that users can only perform actions and access data that they are explicitly permitted to.
+
+## Core Concepts
+
+### Roles
+
+Every user in the system has two distinct roles that define their capabilities:
+
+-   **`appRole`**: Governs permissions within the mobile application.
+    -   `guestUser`: An anonymous user.
+    -   `standardUser`: A registered user.
+    -   `premiumUser`: A user with a premium subscription.
+-   **`dashboardRole`**: Governs permissions for the web-based content management dashboard.
+    -   `none`: No access to the dashboard.
+    -   `publisher`: Can manage content like headlines.
+    -   `admin`: Has full administrative access.
+
+### Permissions
+
+Permissions are granular strings that represent a specific action on a specific resource, following a `resource.action` format.
+
+**Example:** `headline.create`, `user.read_owned`
+
+### The `PermissionService`
+
+This is the central service responsible for authorization checks. It determines a user's total permissions by combining the permissions granted by their `appRole` and `dashboardRole`. Administrators (`dashboardRole: admin`) are automatically granted all permissions.
+
+## Permission Mapping
+
+The `model_registry.dart` file is the single source of truth for mapping API actions (HTTP methods on specific models) to required permissions.
+
+<Aside type="note">
+This centralized registry allows for easy auditing and modification of access control rules without changing the core logic of the route handlers.
+</Aside>
+
+Here's how it works for the generic `/api/v1/data` endpoint:
+
+1.  A request comes in, e.g., `POST /api/v1/data?model=headline`.
+2.  The middleware identifies the model (`headline`) and the method (`POST`).
+3.  It looks up the `headline` configuration in the `modelRegistry`.
+4.  It finds the permission required for the `postPermission` action, which is `adminOnly`.
+5.  It uses the `PermissionService` to check if the authenticated user has the `admin` role.
+6.  If the check fails, the request is rejected with a `403 Forbidden` error.
+
+### Ownership Checks
+
+For user-owned data (like `user_app_settings`), the registry also specifies when an ownership check is required. If a user tries to `GET /api/v1/data/some_other_user_id?model=user_app_settings`, the `ownershipCheckMiddleware` will intervene. It fetches the item, compares its owner ID to the authenticated user's ID, and rejects the request if they don't match (unless the user is an admin).

src/content/docs/api-reference/authentication.mdx

@@ -0,0 +1,204 @@
+---
+title: 'API Reference: Authentication'
+description: Detailed documentation for the authentication endpoints.
+---
+
+import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+
+This section provides a detailed reference for all authentication-related endpoints.
+
+## Endpoints
+
+### Anonymous Sign-In
+
+Creates a new anonymous guest user account. This is typically the first call an app makes on a fresh install to allow users to interact with the app before creating a permanent account.
+
+**Endpoint:** `POST /api/v1/auth/anonymous`
+
+**Authentication:** None required.
+
+#### Success Response (200 OK)
+
+Returns a `SuccessApiResponse` containing an `AuthSuccessResponse` payload with the new anonymous `User` object and a JWT `token`.
+
+<Tabs>
+<TabItem label="Payload">
+```json
+{
+  "data": {
+    "user": {
+      "id": "66a21e2a77f294e7a1f7d41a",
+      "email": "[email protected]",
+      "appRole": "guestUser",
+      "dashboardRole": "none",
+      "createdAt": "2024-07-25T09:30:18.000Z",
+      "feedActionStatus": {
+        // ... default statuses
+      }
+    },
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  },
+  "metadata": {
+    // ...
+  }
+}
+```
+</TabItem>
+</Tabs>
+
+---
+
+### Request Sign-In Code
+
+Initiates the passwordless sign-in/sign-up process by sending a one-time verification code to the user's email.
+
+**Endpoint:** `POST /api/v1/auth/request-code`
+
+**Authentication:** None required.
+
+#### Request Body
+
+<Tabs>
+<TabItem label="Standard Sign-In">
+```json
+{
+  "email": "[email protected]"
+}
+```
+</TabItem>
+<TabItem label="Dashboard Login">
+```json
+{
+  "email": "[email protected]",
+  "isDashboardLogin": true
+}
+```
+</TabItem>
+</Tabs>
+
+-   `email` (string, required): The user's email address.
+-   `isDashboardLogin` (boolean, optional): When `true`, the server first verifies the user exists and has the necessary permissions (`admin` or `publisher`) before sending a code. Defaults to `false`.
+
+#### Success Response (202 Accepted)
+
+An empty body with a `202 Accepted` status code indicates the request was successful and the email is being sent.
+
+#### Error Responses
+
+-   `400 Bad Request`: If the email format is invalid or the request body is malformed.
+-   `401 Unauthorized`: If `isDashboardLogin` is true and the user does not exist.
+-   `403 Forbidden`: If `isDashboardLogin` is true and the user exists but lacks dashboard permissions.
+
+---
+
+### Verify Sign-In Code
+
+Completes the sign-in process by verifying the email and code. This single endpoint handles multiple scenarios:
+
+-   Standard user sign-in.
+-   New user sign-up.
+-   Converting an anonymous guest user to a permanent account.
+-   Dashboard user login.
+
+**Endpoint:** `POST /api/v1/auth/verify-code`
+
+**Authentication:**
+-   **Optional:** If a guest user is converting their account, include their anonymous JWT `Bearer` token in the `Authorization` header.
+-   **None:** For standard sign-in/sign-up flows.
+
+#### Request Body
+
+```json
+{
+  "email": "[email protected]",
+  "code": "123456",
+  "isDashboardLogin": false
+}
+```
+
+-   `email` (string, required): The user's email address.
+-   `code` (string, required): The 6-digit verification code sent to the user's email.
+-   `isDashboardLogin` (boolean, optional): Must be `true` if verifying a code for dashboard access. Defaults to `false`.
+
+#### Success Response (200 OK)
+
+Returns a `SuccessApiResponse` containing an `AuthSuccessResponse` payload with the authenticated `User` object and a new JWT `token`.
+
+#### Error Responses
+
+-   `400 Bad Request`: If the code is invalid, expired, or the request body is malformed.
+-   `403 Forbidden`: If `isDashboardLogin` is true and the user lacks dashboard permissions.
+
+---
+
+### Get Current User
+
+Retrieves the full profile of the currently authenticated user.
+
+**Endpoint:** `GET /api/v1/auth/me`
+
+**Authentication:** Required. A valid JWT `Bearer` token must be provided.
+
+#### Success Response (200 OK)
+
+Returns a `SuccessApiResponse` containing the `User` object.
+
+<Tabs>
+<TabItem label="Payload">
+```json
+{
+  "data": {
+    "id": "66a21e2a77f294e7a1f7d41a",
+    "email": "[email protected]",
+    "appRole": "standardUser",
+    "dashboardRole": "none",
+    // ... other user fields
+  },
+  "metadata": {
+    // ...
+  }
+}
+```
+</TabItem>
+</Tabs>
+
+#### Error Responses
+
+-   `401 Unauthorized`: If the token is missing, invalid, or expired.
+
+---
+
+### Sign Out
+
+Performs server-side sign-out actions, primarily invalidating the current JWT to prevent its reuse.
+
+**Endpoint:** `POST /api/v1/auth/sign-out`
+
+**Authentication:** Required. A valid JWT `Bearer` token must be provided.
+
+#### Success Response (204 No Content)
+
+An empty body with a `204 No Content` status code indicates successful sign-out.
+
+#### Error Responses
+
+-   `401 Unauthorized`: If the token is missing, invalid, or expired.
+
+---
+
+### Delete Account
+
+Permanently deletes the authenticated user's account and all associated data (settings, preferences, etc.).
+
+**Endpoint:** `DELETE /api/v1/auth/delete-account`
+
+**Authentication:** Required. A valid JWT `Bearer` token must be provided.
+
+#### Success Response (204 No Content)
+
+An empty body with a `204 No Content` status code indicates successful account deletion.
+
+#### Error Responses
+
+-   `401 Unauthorized`: If the token is missing, invalid, or expired.
+-   `404 Not Found`: If the user to be deleted does not exist.