diff --git a/.github/ISSUE_TEMPLATE/chore.md b/.github/ISSUE_TEMPLATE/chore.md new file mode 100644 index 0000000..498ebfd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/chore.md @@ -0,0 +1,14 @@ +--- +name: Chore +about: Other changes that don't modify src or test files +title: "chore: " +labels: chore +--- + +**Description** + +Clearly describe what change is needed and why. If this changes code then please use another issue type. + +**Requirements** + +- [ ] No functional changes to the code diff --git a/.github/ISSUE_TEMPLATE/ci.md b/.github/ISSUE_TEMPLATE/ci.md new file mode 100644 index 0000000..fa2dd9e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ci.md @@ -0,0 +1,14 @@ +--- +name: Continuous Integration +about: Changes to the CI configuration files and scripts +title: "ci: " +labels: ci +--- + +**Description** + +Describe what changes need to be done to the ci/cd system and why. + +**Requirements** + +- [ ] The ci system is passing diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ec4bb38 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..f494a4d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,14 @@ +--- +name: Documentation +about: Improve the documentation so all collaborators have a common understanding +title: "docs: " +labels: documentation +--- + +**Description** + +Clearly describe what documentation you are looking to add or improve. + +**Requirements** + +- [ ] Requirements go here diff --git a/.github/ISSUE_TEMPLATE/style.md b/.github/ISSUE_TEMPLATE/style.md new file mode 100644 index 0000000..02244a7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/style.md @@ -0,0 +1,14 @@ +--- +name: Style Changes +about: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc) +title: "style: " +labels: style +--- + +**Description** + +Clearly describe what you are looking to change and why. + +**Requirements** + +- [ ] There is no drop in test coverage. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..1169936 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,27 @@ + + +## Status + +**READY/IN DEVELOPMENT/HOLD** + +## Description + + + +## Type of Change + + + +- [ ] ✨ New feature (non-breaking change which adds functionality) +- [ ] 🛠️ Bug fix (non-breaking change which fixes an issue) +- [ ] ❌ Breaking change (fix or feature that would cause existing functionality to change) +- [ ] 🧹 Code refactor +- [ ] ✅ Build configuration change +- [ ] 📝 Documentation +- [ ] 🗑️ Chore diff --git a/astro.config.mjs b/astro.config.mjs index 261913f..65f4c26 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -33,53 +33,6 @@ export default defineConfig({ items: [ { label: 'Introduction', link: '/api-server/' }, { label: 'Local Setup', link: '/api-server/local-setup' }, - { - label: 'Features', - collapsed: true, - items: [ - { label: 'Overview', link: '/api-server/features/' }, - { label: 'Authentication', link: '/api-server/features/authentication' }, - { label: 'User Data Sync', link: '/api-server/features/user-data-sync' }, - { label: 'Email Service', link: '/api-server/features/email-service' }, - { label: 'Data Management', link: '/api-server/features/data-management-api' }, - { label: 'RBAC', link: '/api-server/features/rbac' }, - { label: 'Rate Limiting', link: '/api-server/features/rate-limiting' }, - ], - }, - { - label: 'Guides', - collapsed: true, - items: [ - { label: 'Overview', link: '/api-server/guides/' }, - { label: 'Configure Environment Variables', link: '/api-server/guides/configure-environment-variables' }, - { label: 'Configure MongoDB', link: '/api-server/guides/configure-mongodb' }, - { label: 'Configure CORS', link: '/api-server/guides/configure-cors' }, - { label: 'Implement an Alternative Email Client', link: '/api-server/guides/implement-alternative-email-client' }, - ], - }, - { - label: 'Architecture', - collapsed: true, - items: [ - { label: 'Overview', link: '/api-server/architecture/' }, - { label: 'Dependency Injection', link: '/api-server/architecture/dependency-injection' }, - { 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' }, - ], - }, - { - label: 'Reference', - collapsed: true, - items: [ - { label: 'Overview', link: '/api-server/reference/' }, - { label: 'Authentication', link: '/api-server/reference/authentication' }, - { label: 'Data Access', link: '/api-server/reference/data-access' }, - { label: 'Core Data Models', link: '/api-server/reference/core-models' }, - ], - }, { label: 'Deployment', link: '/api-server/deployment' }, ], }, @@ -89,43 +42,6 @@ export default defineConfig({ items: [ { label: 'Introduction', link: '/web-dashboard/' }, { label: 'Local Setup', link: '/web-dashboard/local-setup' }, - { - label: 'Features', - collapsed: true, - items: [ - { label: 'Dashboard Overview', link: '/web-dashboard/features/dashboard-overview' }, - { label: 'Content Management', link: '/web-dashboard/features/content-management' }, - { label: 'App Configuration', link: '/web-dashboard/features/app-configuration' }, - { label: 'Authentication', link: '/web-dashboard/features/authentication' }, - ], - }, - { - label: 'Architecture', - collapsed: true, - items: [ - { label: 'Overview', link: '/web-dashboard/architecture/' }, - { label: 'State Management (BLoC)', link: '/web-dashboard/architecture/state-management' }, - { label: 'Routing (go_router)', link: '/web-dashboard/architecture/routing' }, - { label: 'Data Loading Strategy', link: '/web-dashboard/architecture/data-loading-strategy' }, - ], - }, - { - label: 'Guides', - collapsed: true, - items: [ - { label: 'Styling & Theming', link: '/web-dashboard/guides/styling-and-theming' }, - { label: 'Localization', link: '/web-dashboard/guides/localization' }, - ], - }, - { - label: 'Manuals', - collapsed: true, - items: [ - { label: 'Managing Content', link: '/web-dashboard/manuals/managing-content' }, - { label: 'Configuring the Mobile App', link: '/web-dashboard/manuals/configuring-the-app' }, - { label: 'Managing Your Admin Account', link: '/web-dashboard/manuals/managing-admin-account' }, - ], - }, { label: 'Deployment', link: '/web-dashboard/deployment' }, ], }, @@ -135,59 +51,9 @@ export default defineConfig({ items: [ { label: 'Introduction', link: '/mobile-client/' }, { label: 'Local Setup', link: '/mobile-client/local-setup' }, - { - label: 'Architecture', - collapsed: true, - items: [ - { label: 'Overview', link: '/mobile-client/architecture/' }, - { label: 'State Management (BLoC)', link: '/mobile-client/architecture/state-management' }, - { label: 'Routing & Navigation', link: '/mobile-client/architecture/routing' }, - { label: 'Error Handling', link: '/mobile-client/architecture/error-handling' }, - { label: 'Shared Components', link: '/mobile-client/architecture/shared-components' }, - ], - }, - { - label: 'Guides', - collapsed: true, - items: [ - { label: 'Styling & Theming', link: '/mobile-client/guides/styling-and-theming' }, - { label: 'Localization', link: '/mobile-client/guides/localization' }, - ], - }, - { - label: 'Features', - collapsed: true, - items: [ - { label: 'Overview', link: '/mobile-client/features/' }, - { label: 'Account', link: '/mobile-client/features/account' }, - { label: 'Authentication', link: '/mobile-client/features/authentication' }, - { label: 'Ad System', link: '/mobile-client/features/ad-system' }, - { label: 'Headlines Feed', link: '/mobile-client/features/headlines-feed' }, - { label: 'Headline Details', link: '/mobile-client/features/headline-details' }, - { label: 'Entity Details', link: '/mobile-client/features/entity-details' }, - { label: 'Search', link: '/mobile-client/features/search' }, - { label: 'Settings', link: '/mobile-client/features/settings' }, - { label: 'Status Pages', link: '/mobile-client/features/status-pages' }, - ], - }, { label: 'Deployment', link: '/mobile-client/deployment' }, ], }, - { - label: 'Customization Guides', - collapsed: true, - items: [ - { label: 'Overview', link: '/customization/' }, - { - label: 'Hosting Packages for Customization', - link: '/customization/hosting-packages-for-customization', - }, - { - label: 'Guide: Customizing the UI Theme', - link: '/customization/guide-customizing-the-ui', - }, - ], - }, ], }), ], diff --git a/src/content/docs/api-server/architecture/data-access-flow.mdx b/src/content/docs/api-server/architecture/data-access-flow.mdx deleted file mode 100644 index 31a9035..0000000 --- a/src/content/docs/api-server/architecture/data-access-flow.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -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. - - -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. - -7. **Response** - The handler wraps the data from the repository in a standard `SuccessApiResponse` and sends it back to the client. - - ---- - -### 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. - - -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. - - - diff --git a/src/content/docs/api-server/architecture/data-seeding-and-fixtures.mdx b/src/content/docs/api-server/architecture/data-seeding-and-fixtures.mdx deleted file mode 100644 index cd99383..0000000 --- a/src/content/docs/api-server/architecture/data-seeding-and-fixtures.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Data Seeding & System Initialization -description: Learn about the API server's automatic database initialization and seeding process. ---- - -import { Aside } from '@astrojs/starlight/components'; - -A key architectural feature of the API server is its automatic and idempotent database initialization process. This ensures that on first startup, the server correctly prepares the database with the essential indexes and configurations needed to run. - -### The Architectural Goal: A Clean, Predictable Start - -The primary goal of this system is to **guarantee a consistent and predictable state** for the database, especially for new development and production environments. - -This process is designed to be **lean and focused on system setup, not content population**. It handles two critical, one-time tasks: - -1. **Ensuring Database Indexes:** It creates all necessary MongoDB indexes, including TTL (Time-To-Live) indexes for temporary data like verification codes, text indexes for search functionality, and compound indexes to optimize country-related aggregation queries. -2. **Initializing the Admin User:** It securely sets up the single administrator account based on the `OVERRIDE_ADMIN_EMAIL` environment variable. - -### Idempotent and Safe to Run - -The initialization service is **idempotent**. - - - -This is achieved by: -- Using MongoDB's `createIndex` commands, which only create indexes if they don't already exist. -- Intelligently checking for the admin user's existence before attempting to create it. - -This architectural choice provides significant benefits: -- **Reliability:** Ensures the database is always correctly configured for the application to run. -- **Security:** Centralizes and secures the process of setting up the initial administrator. -- **Maintainability:** Keeps the server's core setup logic separate from dynamic application content. diff --git a/src/content/docs/api-server/architecture/dependency-injection.mdx b/src/content/docs/api-server/architecture/dependency-injection.mdx deleted file mode 100644 index cbefaa5..0000000 --- a/src/content/docs/api-server/architecture/dependency-injection.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -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. - - - -## 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((_) => 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()`. - -**Example:** -```dart title="A route handler" -// Read the AuthService provided by the root middleware -final authService = context.read(); - -// 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. diff --git a/src/content/docs/api-server/architecture/error-handling.mdx b/src/content/docs/api-server/architecture/error-handling.mdx deleted file mode 100644 index e6b0359..0000000 --- a/src/content/docs/api-server/architecture/error-handling.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Error Handling -description: An overview of the standardized error responses from the API. ---- - -The API uses a standardized error response format and a consistent set of error codes to make error handling predictable for client applications. - -## Error Response Structure - -All failed requests will return a JSON body with the following structure: - -```json -{ - "error": { - "code": "errorCode", - "message": "A descriptive error message explaining what went wrong." - } -} -``` - -- `code` (string): A machine-readable error code. -- `message` (string): A human-readable description of the error. - -## Common Error Codes - -The following table lists the most common error codes and their corresponding HTTP status codes. - -| HTTP Status | Error Code | Description | -| :---------- | :--------------------- | :------------------------------------------------------------------------------------------------------ | -| `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. | -| `403` | `forbidden` | The authenticated user does not have the necessary permissions to perform the requested action. | -| `404` | `notFound` | The requested resource (e.g., an item with a specific ID) could not be found. | -| `409` | `conflict` | The request could not be completed due to a conflict with the current state of the resource. | -| `429` | `tooManyRequests` | The request was rejected because the client has exceeded the rate limit. | -| `500` | `serverError` | A generic error occurred on the server. | -| `500` | `operationFailed` | A specific, known operation failed on the server for an unexpected reason. | -| `500` | `unknownError` | An unexpected and unhandled error occurred on the server. | -| `503` | `networkError` | The server is temporarily unable to handle the request due to a downstream network issue. | diff --git a/src/content/docs/api-server/architecture/generic-data-endpoint.mdx b/src/content/docs/api-server/architecture/generic-data-endpoint.mdx deleted file mode 100644 index c280873..0000000 --- a/src/content/docs/api-server/architecture/generic-data-endpoint.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -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 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: `/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. - -### The Solution: A Single Endpoint with Registries - -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. -- `POST /api/v1/data?model=source` -> Creates a new source. - -This is made possible by two key components: - -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`). - -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, middleware uses the `ModelRegistry` to authorize the request and the route handlers use the `DataOperationRegistry` to execute the correct data operation. - - - - diff --git a/src/content/docs/api-server/architecture/index.mdx b/src/content/docs/api-server/architecture/index.mdx deleted file mode 100644 index a218d03..0000000 --- a/src/content/docs/api-server/architecture/index.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Architecture Overview -description: Dive deeper into the architectural patterns and advanced concepts of the API server. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -This section explores the core architectural patterns and advanced concepts that underpin the API server, providing a deeper understanding of its design. diff --git a/src/content/docs/api-server/architecture/middleware.mdx b/src/content/docs/api-server/architecture/middleware.mdx deleted file mode 100644 index 226ca87..0000000 --- a/src/content/docs/api-server/architecture/middleware.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: 'Advanced: Middleware & Request Lifecycle' -description: An explanation of the API server's middleware architecture and the detailed request lifecycle for different endpoints. ---- - -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. - -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. - -### The Middleware Chain - -The server defines middleware at different levels of the route tree. Here’s a breakdown of the key middleware and where they are applied: - -- **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. - -- **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. - -- **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`. - -- **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`. - - diff --git a/src/content/docs/api-server/features/authentication.mdx b/src/content/docs/api-server/features/authentication.mdx deleted file mode 100644 index 811cd55..0000000 --- a/src/content/docs/api-server/features/authentication.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: 'Feature: Authentication' -description: A deep dive into the API server's authentication flows, including passwordless sign-in, guest accounts, and token management. ---- - -import { Aside } from '@astrojs/starlight/components'; - -The API server provides a robust and flexible authentication system designed to handle various user scenarios securely. It uses a passwordless email and code flow, supports anonymous guest access, and manages sessions using JSON Web Tokens (JWT). - -### Key Authentication Flows - -#### 1. Passwordless Email + Code Sign-In - -Instead of traditional passwords, the system uses a secure one-time code sent to the user's email address. - -- **Requesting a Code (`/api/v1/auth/request-code`):** The client sends the user's email to this endpoint. The server generates a 6-digit code, stores it temporarily, and emails it to the user. -- **Verifying a Code (`/api/v1/auth/verify-code`):** The client sends the user's email and the 6-digit code. The server validates the code. If correct, it either signs the user in (if they exist) or creates a new account and returns a JWT. - - - -#### 2. Anonymous Guest Sign-In - -- **Creating a Guest Account (`/api/v1/auth/anonymous`):** When a new user opens the app for the first time, the client can call this endpoint to create a temporary guest account. The server returns a new `User` object with a `guestUser` role and a JWT. -- **Guest-to-Permanent Conversion:** If a guest user decides to sign up with their email, the `verify-code` flow intelligently handles the conversion. The guest account's data (like saved preferences) is preserved as the account is upgraded to a `standardUser` role with the verified email. - -#### 3. Session Management with JWT - -All authenticated sessions are managed using JSON Web Tokens (JWT). - -- **Token Generation:** Upon successful authentication, the server generates a JWT containing the user's ID, roles, and an expiration time. -- **Authenticated Requests:** The client must include this token in the `Authorization: Bearer ` header for all subsequent requests to protected endpoints. -- **Middleware:** A dedicated authentication middleware on the server is responsible for validating the token on every incoming request. - -#### 4. Secure Sign-Out - -- **Token Invalidation (`/api/v1/auth/sign-out`):** When a user signs out, the client calls this endpoint. The server adds the token's unique identifier (JTI) to a blacklist, immediately invalidating it even before it naturally expires. This prevents the token from being reused. diff --git a/src/content/docs/api-server/features/data-management-api.mdx b/src/content/docs/api-server/features/data-management-api.mdx deleted file mode 100644 index f1abbc5..0000000 --- a/src/content/docs/api-server/features/data-management-api.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 'Feature: Generic Data API' -description: An explanation of the powerful, model-driven generic data endpoint for managing all application content. ---- - -import { Aside } from '@astrojs/starlight/components'; - -A key architectural feature of the API server is its generic data endpoint, located at `/api/v1/data`. Instead of having separate endpoints for each data type (e.g., `/headlines`, `/topics`), this single, powerful endpoint can manage multiple data models through a simple query parameter. - -This approach simplifies the API surface, reduces code duplication, and makes the system highly extensible. - -### How It Works - -A client makes a standard REST request (GET, POST, PUT, DELETE) to the `/api/v1/data` endpoint and specifies the target data type using the `?model=` query parameter. - -**Example: Fetching all headlines** -```http -GET /api/v1/data?model=headline -``` - -**Example: Fetching a single topic by its ID** -```http -GET /api/v1/data/some-topic-id?model=topic -``` - -**Example: Fetching countries by usage** -```http -GET /api/v1/data?model=country&filter={"usage":"eventCountry"} -``` -This fetches countries that are referenced as 'event countries' in headlines. Similarly, `filter={"usage":"headquarters"}` can be used to fetch countries that are headquarters for sources. - -**Example: Fetching countries by name** -```http -GET /api/v1/data?model=country&filter={"name":"United"} -``` -This fetches countries whose names contain "United", supporting partial and case-insensitive matches. - - - -### The Dual Registry System - -The power behind this generic endpoint comes from two central registries: - -1. **The Model Registry (`ModelRegistry`)**: This registry defines the **rules** for each model. It maps a model name (e.g., `"headline"`) to a configuration object that specifies authorization requirements, ownership details, and how to handle JSON data for that model. - -2. **The Data Operation Registry (`DataOperationRegistry`)**: This registry provides the **actions**. It maps a model name to the actual functions that perform the CRUD operations (Create, Read, Update, Delete). - - - -### Supported Models - -The generic data endpoint can manage the following models out-of-the-box: -- `headline` -- `topic` -- `source` -- `country` -- `language` -- `user` -- `user_app_settings` -- `user_content_preferences` -- `remote_config` -- `dashboard_summary` - - - - diff --git a/src/content/docs/api-server/features/email-service.mdx b/src/content/docs/api-server/features/email-service.mdx deleted file mode 100644 index b1b946d..0000000 --- a/src/content/docs/api-server/features/email-service.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Email Service -description: Learn about the API server's transactional email capabilities. ---- - -import { Aside } from '@astrojs/starlight/components'; - -The API server includes a flexible service for sending transactional emails, which are essential for user authentication flows like sending One-Time Passwords (OTPs). - -### Core Components - -The email functionality is built on a clean, decoupled architecture: - -1. **`EmailClient` Interface:** This is an abstract class that defines the contract for any email-sending service. It requires a single method, `sendTransactionalEmail`. - -2. **`EmailSendGrid` Implementation:** The default implementation provided in the toolkit uses the SendGrid service. It handles the specifics of making API calls to SendGrid. - -3. **`EmailRepository`:** This repository acts as a layer between the business logic and the email client. It abstracts away the specific client being used. - -4. **`AuthService`:** The authentication service uses the `EmailRepository` to trigger sending OTP emails during the sign-in process. - -### How it Works - -When a user requests a sign-in code, the `AuthService` calls the `EmailRepository`, which in turn calls the configured `EmailClient` (by default, `EmailSendGrid`). This layered approach means the `AuthService` doesn't need to know or care about *how* the email is sent, only that it *can* be sent. - - diff --git a/src/content/docs/api-server/features/index.mdx b/src/content/docs/api-server/features/index.mdx deleted file mode 100644 index ac9d1cd..0000000 --- a/src/content/docs/api-server/features/index.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Features -description: Explore the key features and architecture of the API server. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The API server is packed with features designed for a modern, scalable news application. Explore the guides below to understand its core capabilities. - - - - Learn about the secure and flexible authentication flows, including email and anonymous sign-in. - [Read more →](/docs/api-server/features/authentication) - - - Discover how guest user data is seamlessly preserved when they create a permanent account. - [Read more →](/docs/api-server/features/user-data-sync) - - - Understand the decoupled service for sending transactional emails like OTP codes. - [Read more →](/docs/api-server/features/email-service) - - - Explore the granular permission system that secures the API. - [Read more →](/docs/api-server/features/rbac) - - - Learn how the API prevents abuse with built-in request rate limiting. - [Read more →](/docs/api-server/features/rate-limiting) - - diff --git a/src/content/docs/api-server/features/rate-limiting.mdx b/src/content/docs/api-server/features/rate-limiting.mdx deleted file mode 100644 index d4fcd1b..0000000 --- a/src/content/docs/api-server/features/rate-limiting.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: 'Feature: Rate Limiting' -description: An overview of the API server's built-in rate limiting to prevent abuse and ensure stability. ---- - -import { Aside } from '@astrojs/starlight/components'; - -To ensure the stability and security of the API, the server includes a built-in rate-limiting feature. This system automatically tracks the number of requests from a given source and blocks further requests if they exceed a configured limit within a specific time window. - -This is crucial for preventing abuse, such as brute-force attacks on the authentication endpoints or overly aggressive polling of the data API. - -### How It Works - -The rate-limiting mechanism is implemented as a middleware that runs on specific routes. It uses a different strategy for identifying clients depending on the endpoint's sensitivity and authentication requirements. - -There are two distinct rate-limiting configurations applied to different parts of the API: - -1. **IP-Based Limiting for Sensitive Unauthenticated Endpoints:** - - **Target:** The `/api/v1/auth/request-code` endpoint. - - **Identification:** Requests are tracked by the client's **IP address**. - - **Purpose:** This endpoint is unauthenticated and triggers a costly action (sending an email). The rate limit is strict to prevent anonymous users from spamming the service. - - **Default Limit:** 3 requests per IP address per 24 hours. - -2. **User-Based Limiting for Authenticated Endpoints:** - - **Target:** All endpoints under `/api/v1/data`. - - **Identification:** Requests are tracked by the authenticated **user's ID**. - - **Purpose:** This provides a generous limit for general application usage while still protecting the server from excessively frequent requests from a single authenticated user. - - **Default Limit:** 1000 requests per user per 60 minutes. - - - -### Configuration - -These limits are configurable via environment variables, allowing you to adjust them for your specific production needs. For details, see the [Configure Environment Variables](/docs/api-server/guides/configure-environment-variables) guide. - -### Error Response - -When a client exceeds a rate limit, the API will respond with an HTTP `429 Too Many Requests` status code and the following error payload: - -```json -{ - "error": { - "code": "tooManyRequests", - "message": "You have made too many requests. Please try again later." - } -} diff --git a/src/content/docs/api-server/features/rbac.mdx b/src/content/docs/api-server/features/rbac.mdx deleted file mode 100644 index cfafc19..0000000 --- a/src/content/docs/api-server/features/rbac.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: 'Feature: Role-Based Access Control (RBAC)' -description: An overview of the server's permission system for securing API endpoints and actions. ---- - -The API server implements a granular Role-Based Access Control (RBAC) system to ensure that users can only access the data and perform the actions appropriate for their level of authorization. - -The system is built around two key concepts: **Roles** and **Permissions**. - -### Dual-Role System - -Each user in the system has two distinct roles, which combine to define their total permissions: - -1. **`appRole`**: This role governs a user's permissions within the mobile application. The possible values are: - * `guestUser`: For anonymous users with limited access. - * `standardUser`: For authenticated users with regular access. - * `premiumUser`: For subscribed users with access to all app features. - -2. **`dashboardRole`**: This role governs a user's permissions for administrative and content management tasks, primarily through the web dashboard. The possible values are: - * `none`: The default for regular app users with no dashboard access. - * `publisher`: Can manage content like headlines and sources. - * `admin`: Has full control over all system data and settings. - -### Permissions - -Permissions are specific action strings that follow a `resource.action` format (e.g., `headline.create`, `user.read_owned`). A user's combined roles grant them a set of these permissions. - -The `PermissionService` is the core component that checks if a user has a required permission before allowing an action to proceed. - -### How It Works in Practice - -When a user makes an API request, the following happens: - -1. The **Authentication Middleware** verifies the user's JWT and identifies the user. -2. The **Authorization Middleware** determines what permission is required for the requested action (e.g., `headline.create` for a `POST` to `?model=headline`). -3. It then asks the `PermissionService`: "Does this user have the `headline.create` permission?" -4. The `PermissionService` checks the user's `appRole` and `dashboardRole`, looks up the permissions for those roles in the `role_permissions.dart` map, and returns `true` or `false`. -5. If the check passes, the request continues. If it fails, the server returns a `403 Forbidden` error. - -This system provides a secure and centralized way to manage access control across the entire API. diff --git a/src/content/docs/api-server/features/user-data-sync.mdx b/src/content/docs/api-server/features/user-data-sync.mdx deleted file mode 100644 index ce43721..0000000 --- a/src/content/docs/api-server/features/user-data-sync.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: User Data Sync -description: Learn how the API server seamlessly converts anonymous guest users into permanent accounts. ---- - -import { Aside } from '@astrojs/starlight/components'; - -A key feature of the API server's authentication system is its ability to provide a seamless experience for users who start using the app anonymously and later decide to create a permanent account. All of their data, such as saved headlines and followed topics, is automatically carried over. - -### The Guest User Flow - -1. **Anonymous Sign-In:** When a new user opens the mobile app for the first time, the app can perform an "anonymous sign-in". The API server creates a temporary `guestUser` account and returns an authentication token for it. - -2. **Data Accumulation:** The guest user can now use the app normally. They can save headlines, follow topics, and customize their settings. All this data is associated with their temporary `guestUser` ID. - -### The Conversion Process - -When the guest user decides to create a permanent account (e.g., by providing their email and verifying a code), the `AuthService` handles the conversion intelligently: - -1. **Email Verification:** The user provides an email and completes the standard verification process. - -2. **Account Check:** The server checks if a permanent account with the verified email *already exists*. - - - **Scenario A: Account Already Exists:** If a user with that email is found, the server signs them into their existing account. The temporary `guestUser` account and its associated data are deleted, and a new token for the permanent account is issued. This prevents account duplication. - - - **Scenario B: No Account Exists:** If no account is found for the email, the server **converts** the existing `guestUser` record into a `standardUser`. It updates the user's record with the verified email and changes their role. - - diff --git a/src/content/docs/api-server/index.mdx b/src/content/docs/api-server/index.mdx index 4e59020..4b8f113 100644 --- a/src/content/docs/api-server/index.mdx +++ b/src/content/docs/api-server/index.mdx @@ -18,20 +18,4 @@ It is designed to work seamlessly with the [Mobile Client](/docs/mobile-client/) Learn how to deploy the API server to a production environment. [Read more →](/docs/api-server/deployment/) - - Explore the key features of the API server, from authentication to data management. - [Read more →](/docs/api-server/features/) - - - Dive into the architectural patterns that make the server robust and maintainable. - [Read more →](/docs/api-server/architecture/) - - - A complete reference for all API endpoints and data models. - [Read more →](/docs/api-server/reference/) - - - Practical guides for specific configuration and setup tasks. - [Read more →](/docs/api-server/guides/) - diff --git a/src/content/docs/api-server/reference/authentication.mdx b/src/content/docs/api-server/reference/authentication.mdx deleted file mode 100644 index eb87a8f..0000000 --- a/src/content/docs/api-server/reference/authentication.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Authentication API -description: Detailed reference for the authentication endpoints. ---- - -import { Aside } from '@astrojs/starlight/components'; - -This section details the endpoints used for user authentication, including sign-in, sign-up, and session management. - -## Endpoints - -### Request Sign-In Code - -Initiates the sign-in or sign-up process by sending a one-time verification code to the user's email. - -- **Method:** `POST` -- **Path:** `/api/v1/auth/request-code` -- **Body (JSON):** - ```json - { - "email": "user@example.com", - "isDashboardLogin": false - } - ``` - - `email` (string, required): The user's email address. - - `isDashboardLogin` (boolean, optional): Set to `true` when signing in to the admin dashboard. This enforces stricter validation, ensuring the user exists and has the required permissions before sending a code. Defaults to `false`. - -- **Success Response:** - - `202 Accepted`: The request has been accepted, and the email is being sent. - -- **Error Responses:** - - `400 Bad Request`: The email format is invalid, or the request body is malformed. - - `401 Unauthorized`: (`isDashboardLogin: true` only) The user does not exist. - - `403 Forbidden`: (`isDashboardLogin: true` only) The user exists but lacks the required permissions for dashboard access. - -### Verify Sign-In Code - -Verifies the one-time code to complete the sign-in/sign-up process. - -- **Method:** `POST` -- **Path:** `/api/v1/auth/verify-code` -- **Body (JSON):** - ```json - { - "email": "user@example.com", - "code": "123456" - } - ``` - - `email` (string, required): The user's email address. - - `code` (string, required): The 6-digit verification code sent to the user's email. - -- **Success Response:** - - `200 OK`: Returns a standard success response with an `AuthSuccessResponse` payload. - ```json - { - "data": { - "user": { ... }, // The full User object - "token": "ey..." // The JWT authentication token - }, - "metadata": { ... } - } - ``` - -- **Error Responses:** - - `400 Bad Request`: The code is invalid, expired, or the request body is malformed. - - - -### Sign In Anonymously - -Creates a temporary guest account for users who have not yet registered. - -- **Method:** `POST` -- **Path:** `/api/v1/auth/anonymous` -- **Body:** None - -- **Success Response:** - - `200 OK`: Returns a standard success response with an `AuthSuccessResponse` payload, containing the new guest `User` object and a JWT. - -### Get Current User - -Retrieves the profile of the currently authenticated user. - -- **Method:** `GET` -- **Path:** `/api/v1/auth/me` -- **Authentication:** Required (Bearer Token) - -- **Success Response:** - - `200 OK`: Returns a standard success response with the full `User` object as the data payload. - -- **Error Responses:** - - `401 Unauthorized`: The provided token is missing, invalid, or expired. - -### Sign Out - -Performs server-side sign-out actions, primarily invalidating the current authentication token. - -- **Method:** `POST` -- **Path:** `/api/v1/auth/sign-out` -- **Authentication:** Required (Bearer Token) -- **Body:** None - -- **Success Response:** - - `204 No Content`: The token has been successfully invalidated. - -- **Error Responses:** - - `401 Unauthorized`: The provided token is missing, invalid, or expired. - -### Delete Account - -Permanently deletes the authenticated user's account and all associated data. - -- **Method:** `DELETE` -- **Path:** `/api/v1/auth/delete-account` -- **Authentication:** Required (Bearer Token) - -- **Success Response:** - - `204 No Content`: The account has been successfully deleted. - -- **Error Responses:** - - `401 Unauthorized`: The provided token is missing, invalid, or expired. diff --git a/src/content/docs/api-server/reference/core-models.mdx b/src/content/docs/api-server/reference/core-models.mdx deleted file mode 100644 index 3ef0072..0000000 --- a/src/content/docs/api-server/reference/core-models.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Core Data Models -description: A reference for the primary data models used across the API. ---- - -This page provides a reference for the core data models returned by the API. - -## Common Fields - -All primary data models (e.g., `Headline`, `Topic`, `Source`, `Country`) share a common set of fields for identification and tracking. - -- `id` (string): The unique identifier for the document (UUID). -- `createdAt` (string, ISO 8601): The timestamp when the document was created. -- `updatedAt` (string, ISO 8601): The timestamp of the last update. -- `status` (string): The content status. Can be `active`, `draft`, or `archived`. - -## Models - -### User - -Represents a user account in the system. - -- `id` (string): The unique user ID. -- `email` (string): The user's email address. -- `appRole` (string): The user's role within the mobile app (`guestUser`, `standardUser`, `premiumUser`). -- `dashboardRole` (string): The user's role for the admin dashboard (`none`, `publisher`, `admin`). -- `createdAt` (string, ISO 8601): The timestamp of account creation. -- `feedActionStatus` (object): A map tracking the user's interaction with in-feed calls-to-action. - -### Headline - -Represents a single news article. - -- `title` (string): The headline of the article. -- `excerpt` (string): A short summary of the article. -- `url` (string): The URL to the full article. -- `imageUrl` (string): The URL to an associated image. -- `source` (Source): The embedded source object. -- `eventCountry` (Country): The embedded country object where the event took place. -- `topic` (Topic): The embedded topic object. - -### Topic - -Represents a news category. - -- `name` (string): The display name of the topic (e.g., "Technology"). -- `description` (string): A brief description of the topic. -- `iconUrl` (string): A URL to an icon representing the topic. - -### Source - -Represents a news publisher. - -- `name` (string): The name of the news source (e.g., "TechCrunch"). -- `description` (string): A brief description of the source. -- `url` (string): The homepage URL of the source. -- `sourceType` (string): The type of source (e.g., `newsAgency`, `blog`). -- `language` (Language): The embedded language object. -- `headquarters` (Country): The embedded country object where the source is based. - -### Country - -Represents a country. - -- `isoCode` (string): The two-letter ISO 3166-1 alpha-2 code (e.g., "US"). -- `name` (string): The common name of the country (e.g., "United States"). -- `flagUrl` (string): A URL to an image of the country's flag. - -### Language - -Represents a language. - -- `code` (string): The ISO 639-1 code for the language (e.g., "en", "es"). -- `name` (string): The common name of the language (e.g., "English", "Spanish"). -- `nativeName` (string): The name of the language in its own tongue. diff --git a/src/content/docs/api-server/reference/data-access.mdx b/src/content/docs/api-server/reference/data-access.mdx deleted file mode 100644 index 69d3813..0000000 --- a/src/content/docs/api-server/reference/data-access.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Data Access API -description: Detailed reference for the generic data access endpoint. ---- - -import { Aside, Tabs, TabItem } from '@astrojs/starlight/components'; - -The API provides a powerful and generic endpoint for performing CRUD (Create, Read, Update, Delete) operations on all core data models. This approach simplifies client-side code by providing a consistent interface for data interaction. - -- **Endpoint:** `/api/v1/data` -- **Authentication:** Required (Bearer Token) for all methods. - -## The `model` Query Parameter - -Every request to this endpoint **must** include a `model` query parameter to specify which data collection you are targeting. - -- **Example:** `GET /api/v1/data?model=headline` - -### Supported Models - -The following model names are supported: - -- `headline` -- `topic` -- `source` -- `country` (supports specialized filtering by `usage` for 'eventCountry' or 'headquarters') -- `language` -- `user` -- `user_app_settings` -- `user_content_preferences` -- `remote_config` -- `dashboard_summary` - - - - - -## Endpoints - -### List Items (Collection) - -Retrieves a paginated list of items for a specific model. - -- **Method:** `GET` -- **Path:** `/api/v1/data?model=` - -#### Query Parameters - -- **`filter`** (string, optional): A URL-encoded JSON string representing a MongoDB-style query. - -- **`sort`** (string, optional): A comma-separated list of fields to sort by (e.g., `createdAt:desc,title:asc`). -- **`limit`** (integer, optional): The maximum number of items to return. -- **`cursor`** (string, optional): The pagination cursor from a previous response to fetch the next page. - - - - - -**Request:** -``` -GET /api/v1/data?model=headline&filter={"status":"active"} -``` -This fetches all headlines where the `status` field is `"active"`. - - -**Request:** -``` -GET /api/v1/data?model=headline&filter={"topic.id":{"$in":["topicId1","topicId2"]}}&sort=createdAt:desc -``` -This fetches headlines belonging to specific topics, sorted by creation date. - - -**Request:** -``` -GET /api/v1/data?model=country&filter={"usage":"eventCountry"} -``` -This fetches all countries that are referenced as 'event countries' in headlines. - - - -- **Success Response:** - - `200 OK`: Returns a standard success response with a `PaginatedResponse` object as the data payload. - -### Create Item - -Creates a new item for a specific model. - -- **Method:** `POST` -- **Path:** `/api/v1/data?model=` -- **Body (JSON):** The JSON representation of the model to create. The `id`, `createdAt`, and `updatedAt` fields will be automatically generated by the server and should be omitted from the request body. - -- **Success Response:** - - `201 Created`: Returns a standard success response with the newly created item object as the data payload. - -### Read Item - -Retrieves a single item by its unique ID. - -- **Method:** `GET` -- **Path:** `/api/v1/data/?model=` - -- **Success Response:** - - `200 OK`: Returns a standard success response with the requested item object as the data payload. - -- **Error Responses:** - - `404 Not Found`: The item with the specified ID does not exist. - -### Update Item - -Updates an existing item by its unique ID. - -- **Method:** `PUT` -- **Path:** `/api/v1/data/?model=` -- **Body (JSON):** The full JSON representation of the model with the updated fields. - - - -- **Success Response:** - - `200 OK`: Returns a standard success response with the updated item object as the data payload. - -- **Error Responses:** - - `404 Not Found`: The item with the specified ID does not exist. - -### Delete Item - -Deletes an item by its unique ID. - -- **Method:** `DELETE` -- **Path:** `/api/v1/data/?model=` - -- **Success Response:** - - `204 No Content`: The item was successfully deleted. - -- **Error Responses:** - - `404 Not Found`: The item with the specified ID does not exist. diff --git a/src/content/docs/api-server/reference/index.mdx b/src/content/docs/api-server/reference/index.mdx deleted file mode 100644 index 40cb304..0000000 --- a/src/content/docs/api-server/reference/index.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: API Reference -description: A complete reference for the Flutter News App API, covering authentication, data access, and error handling. ---- - -import { Card, CardGrid, Aside } from '@astrojs/starlight/components'; - -Welcome to the complete API reference for the Flutter News App backend. This section provides detailed information about every endpoint, including request formats, response payloads, and authentication requirements. - -## Base URL & Versioning - -All API endpoints are prefixed with a base URL and a version number. - -- **Base URL:** `http://localhost:8080` (for local development) -- **API Version:** `v1` - -The full path for an endpoint will look like: `http://localhost:8080/api/v1/...` - -## Authentication - -Most endpoints require authentication. The API uses **Bearer Token** authentication, where a valid JSON Web Token (JWT) must be included in the `Authorization` header of your requests. - -``` -Authorization: Bearer -``` - -You can obtain a token through the endpoints detailed in the [Authentication Guide](./authentication/). - -## Standard Responses - -The API uses a standardized format for both successful and error responses to ensure consistency. - -### Success Response - -Successful requests (HTTP `200 OK`, `201 Created`) will return a JSON object with the following structure: - -```json -{ - "data": { - // The main data payload, which can be an object or an array - }, - "metadata": { - "requestId": "a-unique-request-id", - "timestamp": "2023-10-27T10:00:00.000Z" - } -} -``` - -### Error Response - -Failed requests will return an appropriate HTTP status code (e.g., `400`, `401`, `403`, `404`, `500`) and a JSON body with a consistent error structure: - -```json -{ - "error": { - "code": "errorCode", - "message": "A descriptive error message." - } -} -``` - - - -## API Endpoint Guides - - - - Endpoints for user sign-up, sign-in, and session management. - [Read more →](/docs/api-server/reference/authentication/) - - - The generic endpoint for all CRUD operations on data models. - [Read more →](/docs/api-server/reference/data-access/) - - diff --git a/src/content/docs/customization/guide-customizing-the-ui.mdx b/src/content/docs/customization/guide-customizing-the-ui.mdx deleted file mode 100644 index 41ce593..0000000 --- a/src/content/docs/customization/guide-customizing-the-ui.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: 'Guide: Customizing the UI Theme' -description: A practical, step-by-step guide to customizing the UI theme by creating a private copy of the ui_kit package. ---- -import { Steps, Aside } from '@astrojs/starlight/components'; - -This guide provides a hands-on, practical walkthrough of the most common and impactful customization task: changing the application's visual theme. - -By following this guide, you will learn the complete, end-to-end workflow for modifying a shared package and seeing that change reflected in both the Mobile Client and the Web Dashboard. - -### The Goal - -Our goal is to change the default blue accent color of the application to a new color, for example, deep purple. To do this, we will create a private copy of the `ui_kit` package, modify its theme file, and then instruct both of our Flutter applications to use our modified version. - - -1. **Host a Private Copy of the `ui_kit` Package** - - Before you can change any code, you must have your own version of the `ui_kit` package hosted in a private repository. - - - Follow the [**Hosting Packages for Customization**](/docs/customization/hosting-packages-for-customization/) guide from start to finish, but for the `ui_kit` repository. - - **Clone URL:** `https://github.com/flutter-news-app-full-source-code/ui-kit.git` - - Once you have successfully pushed the `ui_kit` code to your own private GitHub repository, you are ready to proceed. - -2. **Modify the Theme Code** - - Now, open the `ui_kit` package you cloned to your local machine in your code editor (e.g., VS Code). - - - Navigate to and open the file: `lib/src/theme/app_theme.dart`. - - Locate the `_commonSubThemesData` constant. This is where you can make global changes to widget styles. - - Let's change the `appBarBackgroundSchemeColor` to `primary` to make the app bar more prominent. - - ```dart title="ui_kit/lib/src/theme/app_theme.dart" - const FlexSubThemesData _commonSubThemesData = FlexSubThemesData( - // ... - // Change the app bar background color - appBarBackgroundSchemeColor: SchemeColor.primary, // Changed from .surface - // ... - ); - ``` - -3. **Commit and Push Your Changes** - - Save the file, then commit and push this change to *your private* `ui_kit` repository. - - ```bash - # From inside your local ui_kit directory - git add . - git commit -m "feat: change app bar theme color" - git push - ``` - -4. **Update the Mobile Client** - - Now it's time to see your change in action. Open the **Mobile Client** project (`flutter-news-app-mobile-client-full-source-code`) in your code editor. - - - Open the `pubspec.yaml` file. - - Locate the `ui_kit` dependency. - - Change the `url` to point to your private repository's URL. - - ```yaml title="Mobile Client's pubspec.yaml" - dependencies: - # ... other dependencies - ui_kit: - git: - # Replace this with the URL of YOUR private repository - url: https://github.com/YOUR_USERNAME/YOUR_UI_KIT_REPO.git - # ... other dependencies - ``` - - - Now, run `flutter pub upgrade` in the terminal for the Mobile Client project. This will fetch the updated code from your private repository. - - ```bash - flutter pub upgrade ui_kit - ``` - - - Relaunch the mobile app (`flutter run`). You should now see your new theme color applied to the app bar! - -5. **Update the Web Dashboard** - - The final step is to apply the exact same change to the Web Dashboard, demonstrating the power of the shared package. - - - Open the **Web Dashboard** project (`flutter-news-app-web-dashboard-full-source-code`). - - Open its `pubspec.yaml` file. - - Update the `ui_kit` dependency's `url` to point to your private repository, just as you did for the mobile client. - - Run `flutter pub upgrade ui_kit` in the terminal for the Web Dashboard project. - - Relaunch the web app (`flutter run -d chrome`). The dashboard will now also have the new app bar color. - - - -### Conclusion - -You have successfully completed the core customization workflow. You now have a privately hosted and modified `ui_kit` package that is consumed by both of your client applications. You can use this exact same process to customize any other shared package in the toolkit. diff --git a/src/content/docs/customization/hosting-packages-for-customization.mdx b/src/content/docs/customization/hosting-packages-for-customization.mdx deleted file mode 100644 index f0c19e2..0000000 --- a/src/content/docs/customization/hosting-packages-for-customization.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: 'Hosting Packages for Customization' -description: A step-by-step guide to creating your own version of the shared packages to enable modification. ---- -import { Steps, Aside } from '@astrojs/starlight/components'; - -To enable customization of the Flutter News App Toolkit, you must host your own version of the shared packages. The applications (Mobile Client, Web Dashboard) are designed to be customized, but the deepest and most impactful changes—like altering data models or redesigning the UI theme—happen within the shared packages. - -This guide will walk you through the essential process of creating a private copy of a shared package from the original public repository. - - - -### Why You Must Host a Private Copy - -- **To Enable Modification:** You cannot push changes to the original public repositories. To modify a package, you need your own version that you control. -- **For Privacy and Control:** Hosting the packages in your own private repositories ensures that your proprietary changes, business logic, and customizations remain confidential. -- **To Manage Updates:** It gives you full control over when and how you pull in future updates from the original toolkit. - -### The Workflow: A Step-by-Step Guide - -Let's walk through the process using the `core` package as an example. You will repeat these steps for any other package you wish to customize, such as `ui_kit` or `data_repository`. - - -1. **Clone the Original Package Repository** - - First, clone the package's repository from the public GitHub organization to your local machine. Make sure you are **not** inside another Git repository when you do this. - - ```bash - # Clone the 'core' package repository - git clone https://github.com/flutter-news-app-full-source-code/core.git - - # Navigate into the newly cloned directory - cd core - ``` - -2. **Create a New Private Repository on GitHub** - - Go to your GitHub account and create a new **private** repository. - - Name it appropriately (e.g., `my-company-core-package`). - - **Do not** initialize it with a README, .gitignore, or license file, as we will be pushing an existing repository. - -3. **Update the Git Remote URL** - - Back in your terminal, inside the `core` directory you cloned, you need to change the Git "remote" from the original public repository to your new private one. - - First, view the existing remote: - ```bash - git remote -v - # origin https://github.com/flutter-news-app-full-source-code/core.git (fetch) - # origin https://github.com/flutter-news-app-full-source-code/core.git (push) - ``` - - Now, change the URL to point to your new private repository: - ```bash - git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_NEW_PRIVATE_REPO_NAME.git - ``` - Replace `YOUR_USERNAME` and `YOUR_NEW_PRIVATE_REPO_NAME` with your actual GitHub details. - -4. **Push the Code to Your Private Repository** - - Finally, push the package code to your new private repository. - - ```bash - git push -u origin --all - git push -u origin --tags - ``` - - - -You have now successfully created a private copy of the `core` package. It is now hosted in your private repository, ready for any modifications you need to make. - -The next step is to tell your applications (Mobile Client, Web Dashboard) to use *your* version of the package instead of the original one. The next guide, [**Guide: Customizing the UI Theme**](/docs/customization/guide-customizing-the-ui/), will walk you through this process in a practical, hands-on example. diff --git a/src/content/docs/customization/index.mdx b/src/content/docs/customization/index.mdx deleted file mode 100644 index 69fa654..0000000 --- a/src/content/docs/customization/index.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: 'Customization Guides' -description: Learn how to modify the shared packages to customize your applications. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -This section provides practical, hands-on guides for customizing the toolkit by modifying the shared packages. Following these guides is the key to unlocking the full potential of the source code. - - - - This is the most critical guide. Learn how to create your own private version of a shared package to enable modification. - [Read more →](/docs/customization/hosting-packages-for-customization/) - - - Put theory into practice with a hands-on tutorial for customizing the UI theme by modifying the `ui_kit` package. - [Read more →](/docs/customization/guide-customizing-the-ui/) - - diff --git a/src/content/docs/mobile-client/architecture/error-handling.mdx b/src/content/docs/mobile-client/architecture/error-handling.mdx deleted file mode 100644 index bf8d7f9..0000000 --- a/src/content/docs/mobile-client/architecture/error-handling.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Error Handling -description: Learn how errors and exceptions are managed across the application layers. ---- -import { Aside } from '@astrojs/starlight/components'; - -The mobile client employs a standardized and robust error handling strategy to ensure that issues are managed gracefully and that users are presented with clear, helpful feedback. The strategy is built upon a set of custom exception classes defined in the shared `core` package. - -### The Standardized Exceptions - -All exceptions that represent business logic or data fetching errors are subtypes of `HttpException`. This provides a consistent set of errors that can be handled across the entire application. Examples include: - -- `NotFoundException`: Thrown when a requested resource does not exist. -- `NetworkException`: Thrown for connectivity issues like timeouts or DNS failures. -- `UnauthorizedException`: Thrown for authentication or authorization failures. -- `OperationFailedException`: A general-purpose exception for other server-side or unexpected failures. - - - -### The Flow of an Exception - -The error handling strategy follows the application's layered architecture, ensuring that exceptions are caught and handled at the appropriate level. - -1. **Data Layer**: The `DataApi` client is responsible for making HTTP requests. It wraps all `try/catch` blocks around these requests. If a `DioException` (from the `http_client` package) occurs, an `ErrorInterceptor` maps it to one of the standardized `HttpException` subtypes. This is the only layer where raw network exceptions are handled. - -2. **Repository Layer**: The `DataRepository` calls the data clients. It does not typically handle exceptions itself but allows them to propagate upwards. This keeps the repository focused on its role as a data aggregator. - -3. **Business Logic Layer (BLoC)**: The BLoC is where exceptions are ultimately handled. A BLoC will wrap its calls to the repository in a `try/catch` block. - - If an operation is successful, it emits a `Success` state with the fetched data. - - If an `HttpException` is caught, it emits a `Failure` state, capturing the exception. - - ```dart title="lib/headlines-feed/bloc/headlines_feed_bloc.dart" - // ... - try { - final headlineResponse = await _headlinesRepository.readAll(/* ... */); - // ... - emit(state.copyWith(status: HeadlinesFeedStatus.success, /* ... */)); - } on HttpException catch (e) { - emit(state.copyWith(status: HeadlinesFeedStatus.failure, error: e)); - } - // ... - ``` - -4. **Presentation Layer (UI)**: The UI uses a `BlocBuilder` to listen for state changes from the BLoC. - - When it receives a `Success` state, it renders the data. - - When it receives a `Failure` state, it displays a user-friendly error message using the shared `FailureStateWidget`. This widget takes the exception from the state and uses a helper method (`toFriendlyMessage`) to convert it into a localized, human-readable string. - -This structured approach ensures that UI components are never directly responsible for error handling logic, leading to a cleaner and more maintainable codebase. diff --git a/src/content/docs/mobile-client/architecture/index.mdx b/src/content/docs/mobile-client/architecture/index.mdx deleted file mode 100644 index 83a4310..0000000 --- a/src/content/docs/mobile-client/architecture/index.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Architecture Overview -description: An overview of the mobile client's layered architecture. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Flutter mobile client is built upon a clean, layered architecture designed for scalability, testability, and maintainability. This structure separates concerns, making the codebase easier to understand and extend. - -The architecture is divided into four primary layers: - - - - This is the lowest layer, responsible for all communication with external data sources. It consists of **Data Client** implementations (e.g., `DataApi` for HTTP requests, `DataInMemory` for mock data). This layer handles the raw data fetching and maps external errors to a set of standardized exceptions. - - - The Repository Layer abstracts the data sources from the rest of the application. It uses the Data Clients to perform CRUD operations but hides the implementation details. This layer provides a clean, consistent API for the Business Logic Layer to consume. - - - This layer contains the application's state and business logic, implemented using the **BLoC (Business Logic Component)** pattern. BLoCs respond to events from the UI, interact with repositories to fetch or update data, and emit new states for the UI to render. - - - The top layer, responsible for rendering the user interface. It is composed of Flutter widgets that listen to state changes from BLoCs and dispatch events based on user interaction. This layer contains no business logic; it is purely concerned with presentation. - - - -This layered approach ensures a unidirectional data flow, making the application's state predictable and easy to debug. diff --git a/src/content/docs/mobile-client/architecture/routing.mdx b/src/content/docs/mobile-client/architecture/routing.mdx deleted file mode 100644 index d32ba1b..0000000 --- a/src/content/docs/mobile-client/architecture/routing.mdx +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Routing & Navigation -description: Learn about the startup flow and routing architecture that powers the mobile client. ---- -import { Card, CardGrid, Aside } from '@astrojs/starlight/components'; - -The mobile client employs a sophisticated, multi-path startup sequence to handle authentication and remote configuration checks gracefully. This ensures the app is always in a valid state before rendering the main UI. - -## The Application Startup Flow - -The startup logic is orchestrated by the `AppBloc` and the root `_AppView` widget. The path the user experiences depends on their initial authentication status. - - - -### Path 1: New or Logged-Out User - -This is the flow for a user with no existing session. - -1. **Auth Check**: On startup, the `AppBloc` checks for a user. None is found. -2. **State Transition**: The `AppBloc` immediately emits the `AppStatus.unauthenticated` state. -3. **Router Activation**: The `_AppView` widget sees a "running" state (`unauthenticated`) and builds the main `MaterialApp.router`, activating `GoRouter`. -4. **Redirection**: `GoRouter`'s `redirect` logic intercepts the navigation, sees the `unauthenticated` status, and immediately redirects the user to the `/authentication` page. - -In this scenario, the user is taken directly to the sign-in screen without any intermediate loading pages. - -### Path 2: Existing User (Authenticated or Anonymous) - -This flow handles users who already have an active session, ensuring stability by performing critical checks before rendering the main UI. - -1. **Auth Check**: On startup, the `AppBloc` finds an existing user session. -2. **Initial State**: The `AppBloc` emits the corresponding status (`authenticated` or `anonymous`) and immediately dispatches an `AppConfigFetchRequested` event. -3. **Pre-Router Status Pages**: The `_onAppConfigFetchRequested` handler sets the state to `AppStatus.configFetching`. The `_AppView` widget detects this critical status and displays a full-screen `StatusPage` *before* building the main router. This stable startup sequence is critical and handles several possibilities: - - **Loading**: A `StatusPage` with a loading indicator is shown. - - **Failure**: If the config fetch fails, the `StatusPage` shows a retry button. - - **Maintenance/Update**: If the config dictates, a `MaintenancePage` or `UpdateRequiredPage` is shown. -4. **Router Activation**: Only after the remote config is successfully fetched and no critical status is found does the `_AppView` build the `MaterialApp.router`. -5. **Redirection**: `GoRouter`'s `redirect` logic sees the `authenticated` or `anonymous` status and navigates the user to the main `/feed`. - -This two-path system correctly prioritizes authentication and then uses that session to securely fetch critical app configuration. - - - -## GoRouter Implementation Details - -Once the startup flow is complete and the router is active, `go_router` manages all in-app navigation. - -### Core Concepts - -- **`GoRouter`**: The main router instance that controls the application's navigation stack. It is configured with a list of routes, redirect logic, and a refresh listener. - -- **`Routes` Class**: A class located in `lib/router/routes.dart` that defines all route paths and names as `static const String` constants. Using named routes (e.g., `context.goNamed(Routes.settingsName)`) instead of raw path strings is a best practice that prevents typos and makes the code more maintainable. - -- **`StatefulShellRoute`**: This is a key component from `go_router` used to implement persistent UI elements, such as the main bottom navigation bar. It wraps the main sections of the app (e.g., Headlines Feed, Search, Account) and manages a separate navigation stack for each section, preserving the navigation state as the user switches between tabs. - -### Key Implementations - - - - All route definitions are located in `lib/router/router.dart`. This file contains the `GoRouter` setup, including the tree of `GoRoute` and `StatefulShellRoute` widgets that define the entire navigation map of the application. - - - The router is configured with a `redirect` logic that depends on the application's authentication status, which is provided by the `AppBloc`. This ensures that unauthenticated users are automatically redirected to the sign-in page, while authenticated users are directed to the main app content, creating a secure and seamless user experience. - - - By using named routes defined in the `Routes` class, navigation calls throughout the app are type-safe. This approach reduces runtime errors and makes it easy to refactor or update routes, as any changes only need to be made in one central location. - - - The router is used to pass complex data between pages. For example, when navigating to a details page, the full `Headline` object is passed via the `extra` parameter of the navigation call. This is more efficient than passing an ID and re-fetching data that is already available. - - - -### Route Structure - -The main application routes are structured using a `StatefulShellRoute`, which provides the bottom navigation bar. Top-level routes are used for pages that should appear over the main shell, such as authentication or detailed content views. - -```tree title="Main Route Tree" -/ -├─ /feed -│ ├─ article/:id -│ ├─ notifications -│ └─ filter -│ ├─ topics -│ └─ sources -├─ /search -│ └─ article/:id -└─ /account - ├─ settings - │ ├─ appearance - │ │ ├─ theme - │ │ └─ font - │ ├─ feed - │ └─ language - ├─ manage-followed-items - │ ├─ topics - │ │ └─ add-topic - │ └─ sources - │ └─ add-source - └─ saved-headlines - └─ article/:id -``` -## Core Concepts - -- **`GoRouter`**: The main router instance that controls the application's navigation stack. It is configured with a list of routes, redirect logic, and a refresh listener. - -- **`Routes` Class**: A class located in `lib/router/routes.dart` that defines all route paths and names as `static const String` constants. Using named routes (e.g., `context.goNamed(Routes.settingsName)`) instead of raw path strings is a best practice that prevents typos and makes the code more maintainable. - -- **`StatefulShellRoute`**: This is a key component from `go_router` used to implement persistent UI elements, such as the main bottom navigation bar. It wraps the main sections of the app (e.g., Headlines Feed, Search, Account) and manages a separate navigation stack for each section, preserving the navigation state as the user switches between tabs. - -## Key Implementations - - - - All route definitions are located in `lib/router/router.dart`. This file contains the `GoRouter` setup, including the tree of `GoRoute` and `StatefulShellRoute` widgets that define the entire navigation map of the application. - - - The router is configured with a `redirect` logic that depends on the application's authentication status, which is provided by the `AppBloc`. This ensures that unauthenticated users are automatically redirected to the sign-in page, while authenticated users are directed to the main app content, creating a secure and seamless user experience. - - - By using named routes defined in the `Routes` class, navigation calls throughout the app are type-safe. This approach reduces runtime errors and makes it easy to refactor or update routes, as any changes only need to be made in one central location. - - - The router is used to pass complex data between pages. For example, when navigating to a details page, the full `Headline` object is passed via the `extra` parameter of the navigation call. This is more efficient than passing an ID and re-fetching data that is already available. - - - -### Route Structure - -The main application routes are structured using a `StatefulShellRoute`, which provides the bottom navigation bar. Top-level routes are used for pages that should appear over the main shell, such as authentication or detailed content views. - -```tree title="Main Route Tree" -/ -├─ /feed -│ ├─ article/:id -│ ├─ notifications -│ └─ filter -│ ├─ topics -│ └─ sources -├─ /search -│ └─ article/:id -└─ /account - ├─ settings - │ ├─ appearance - │ │ ├─ theme - │ │ └─ font - │ ├─ feed - │ └─ language - ├─ manage-followed-items - │ ├─ topics - │ │ └─ add-topic - │ └─ sources - │ └─ add-source - └─ saved-headlines - └─ article/:id -``` diff --git a/src/content/docs/mobile-client/architecture/shared-components.mdx b/src/content/docs/mobile-client/architecture/shared-components.mdx deleted file mode 100644 index ebcdfe2..0000000 --- a/src/content/docs/mobile-client/architecture/shared-components.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Shared Components & UI Kit -description: Discover the reusable widgets and UI conventions that ensure a consistent user experience. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -A key principle of the mobile client's architecture is the extensive use of shared components to maintain a consistent, high-quality, and maintainable user interface. This is achieved through a combination of a dedicated `ui_kit` package and a local `lib/shared/` directory within the mobile client project. - -## The `ui_kit` Package - -The `ui_kit` package is a shared library that contains the foundational elements of the application's design system. This includes: - -- **`AppTheme`**: Defines the application's light and dark themes, including color schemes, typography, and sub-theme data for widgets like `Card` and `AppBar`. -- **`AppSpacing`**: A collection of `static const double` values for consistent padding, margins, and spacing throughout the UI. -- **Core Widgets**: Common, stateless widgets like `LoadingStateWidget` and `FailureStateWidget` that are used across multiple features to provide a uniform user experience for common application states. - -By centralizing these core UI elements in a shared package, we ensure that all applications in the ecosystem (mobile, web dashboard) can maintain a consistent visual identity. - -## Local Shared Widgets (`lib/shared/widgets/`) - -The mobile client's local `lib/shared/widgets/` directory contains reusable widgets that are specific to the mobile app but are used across multiple features. The most prominent examples are the `HeadlineTile` widgets. - - - - This widget is used when the user's feed preference is set to show a large thumbnail. It displays a prominent image at the top of the card, with the title and metadata below. - - - Used for the "small thumbnail" feed preference, this widget displays a smaller, square image at the start of the tile, with the title and metadata to the right. - - - For users who prefer a more compact, text-focused feed, this widget displays only the headline's title and metadata, with no image. - - - -By abstracting the headline presentation into these shared widgets, the application can easily switch between different display styles based on user settings, and any future design changes only need to be made in one place. diff --git a/src/content/docs/mobile-client/architecture/state-management.mdx b/src/content/docs/mobile-client/architecture/state-management.mdx deleted file mode 100644 index 48c3d41..0000000 --- a/src/content/docs/mobile-client/architecture/state-management.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: State Management (BLoC) -description: An explanation of the BLoC pattern for state management in the mobile client. ---- -import { Aside } from '@astrojs/starlight/components'; - -The mobile client uses the **BLoC (Business Logic Component)** pattern for state management. This pattern helps to separate the presentation layer from the business logic, making the application more structured, testable, and maintainable. - -While most features have their own dedicated BLoC, the most important one is the global `AppBloc`, which manages the application's core state, including user authentication, settings, and the overall application status (`AppStatus`). - -Every feature in the application that requires managing state has its own BLoC. - -### The Core Components of BLoC - -A BLoC is made up of three main parts: - -1. **Events**: Events are the inputs to a BLoC. They are dispatched from the UI in response to user interactions (e.g., a button press) or lifecycle events (e.g., the page loading). Events are defined as simple classes that extend a base `Event` class. - -2. **States**: States are the outputs of a BLoC. They represent a part of the application's state and are emitted by the BLoC in response to events. The UI listens to the stream of states and rebuilds itself to reflect the latest state. States are typically modeled as immutable classes. - -3. **BLoC**: The BLoC itself is the component that sits between the UI and the data layer. It receives events, processes them (often by interacting with a repository), and emits new states. - -### A Practical Example: `AccountBloc` - -Let's look at the `AccountBloc`, which manages the state for the user's account screen. - -- **Event**: When a user toggles following a topic, the UI dispatches an `AccountFollowTopicToggled` event, which contains the `Topic` object. - - ```dart title="lib/account/bloc/account_event.dart" - class AccountFollowTopicToggled extends AccountEvent { - const AccountFollowTopicToggled({required this.topic}); - final Topic topic; - } - ``` - -- **BLoC Logic**: The `AccountBloc` listens for this event. In its event handler, it updates the user's preferences by calling the `_userContentPreferencesRepository` and then emits a new state. - - ```dart title="lib/account/bloc/account_bloc.dart" - on(_onAccountFollowTopicToggled); - - Future _onAccountFollowTopicToggled( - AccountFollowTopicToggled event, - Emitter emit, - ) async { - // ... logic to add/remove topic from preferences ... - final updatedPrefs = // ... - - // Persist the change - await _userContentPreferencesRepository.update(item: updatedPrefs); - - // Emit the new state - emit(state.copyWith(status: AccountStatus.success, preferences: updatedPrefs)); - } - ``` - -- **State**: The `AccountState` holds the current user's `UserContentPreferences`. When the BLoC emits a new state with the updated preferences, the UI rebuilds. - - ```dart title="lib/account/bloc/account_state.dart" - class AccountState extends Equatable { - const AccountState({ - this.status = AccountStatus.initial, - this.preferences, - // ... - }); - - final AccountStatus status; - final UserContentPreferences? preferences; - // ... - } - ``` - -- **UI Integration**: The `FollowedTopicsListPage` uses a `BlocBuilder` to listen to the `AccountBloc`. When the state changes, it rebuilds the list of topics, and the UI reflects whether the topic is followed or not. - - ```dart title="lib/account/view/manage_followed_items/topics/followed_topics_list_page.dart" - // ... - body: BlocBuilder( - builder: (context, state) { - // ... build UI based on state.preferences.followedTopics ... - }, - ), - // ... - ``` - -This unidirectional data flow—from UI event to BLoC to new UI state—is the foundation of state management in the application. diff --git a/src/content/docs/mobile-client/features/account.mdx b/src/content/docs/mobile-client/features/account.mdx deleted file mode 100644 index 9f5f8b5..0000000 --- a/src/content/docs/mobile-client/features/account.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Account Management -description: Learn how users can manage their preferences, saved articles, and followed content. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Account section serves as the user's personal hub within the application. From here, they can view their profile, manage their content preferences, access saved articles, and control their sign-in status. - -## Core Components - -- **`AccountBloc`**: This is the primary BLoC for managing a user's content preferences (`UserContentPreferences`). It listens for changes in the user's authentication state from the `AppBloc`. When a user signs in, it loads their preferences. It also handles all actions related to modifying these preferences, such as saving an article or following a topic. - -- **`AccountPage`**: The main UI for this feature. It displays the user's email or an "Anonymous" status, provides a sign-out or link-account button, and offers navigation to sub-pages for managing saved and followed content. - -- **`SavedHeadlinesPage`**: A dedicated page that displays a list of all the headlines the user has saved. Users can view or remove articles from this list. - -## Key Functionalities - - - - The `AccountBloc` is responsible for fetching, creating, and updating a user's `UserContentPreferences` object. This single object holds all of the user's content-related settings, including lists of followed topics, followed sources, and saved headlines. - - - Users can save any headline for later reading. This action dispatches an `AccountSaveHeadlineToggled` event to the `AccountBloc`. The `SavedHeadlinesPage` then displays a clean, scrollable list of these saved articles. - - - The "Content Preferences" section allows users to manage the topics and sources they follow. This is where the `AvailableTopicsBloc` and `AvailableSourcesBloc` are used to fetch lists of all available entities that the user can choose to follow or unfollow. - - - The `AccountPage` intelligently adapts its UI based on the user's status. For anonymous users, it presents a clear call-to-action to "link" their account, providing a smooth transition to the authentication flow to save their preferences permanently. - - diff --git a/src/content/docs/mobile-client/features/ad-system.mdx b/src/content/docs/mobile-client/features/ad-system.mdx deleted file mode 100644 index a245bf4..0000000 --- a/src/content/docs/mobile-client/features/ad-system.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 'Feature: Ad System' -description: Learn about the provider-agnostic ad system for monetization. ---- -import { Card, CardGrid, Aside } from '@astrojs/starlight/components'; - -The mobile client includes a sophisticated, provider-agnostic ad system designed for monetization while ensuring architectural stability and a smooth user experience. - -## Core Architecture - -The ad system is built on a decoupled architecture that avoids tying the application to a single ad network SDK. - - - - The system uses a generic `NativeAd` model and an abstract `AdProvider` interface. This allows the application to use different ad networks by creating a new implementation of the `AdProvider`. The initial implementation is for **Google AdMob**. - - - A critical challenge with native ad SDKs is managing the lifecycle of ad objects, which can lead to crashes if not handled correctly. This system solves this by managing ad objects within a `StatefulWidget` (`AdmobNativeAdWidget`) and a central `AdCacheService`, preventing premature disposal of ads that are scrolled off-screen. - - - The `AdCacheService` acts as a singleton that stores loaded native ads. When an ad slot scrolls into view, the app first checks the cache. This prevents redundant network requests, leading to smoother scrolling and reduced data usage. The cache is strategically cleared on major content refreshes to ensure ad relevance. - - - On platforms where native ad SDKs are not supported (like web), a `NoOpAdProvider` is used. This provider renders a visual placeholder instead of a real ad, which prevents `MissingPluginException` crashes at startup and allows for consistent UI testing across all platforms. - - - -## Integration with the Feed - -The ad system is seamlessly integrated into any scrollable list of content, such as the main headlines feed or entity details pages. - -- **`FeedDecoratorService`**: This service is responsible for injecting `AdPlaceholder` objects into the feed's content list based on rules defined in the `RemoteConfig`. These placeholders are simple, stateless markers indicating where an ad should appear. - -- **`AdLoaderWidget`**: This `StatefulWidget` is rendered when an `AdPlaceholder` is in the list. It contains the logic to: - 1. Check the `AdCacheService` for a cached ad corresponding to the placeholder's ID. - 2. If no ad is cached, it requests a new one from the `AdService`. - 3. It manages its own loading and error states, displaying a shimmer while loading or a placeholder on failure. - 4. Once an ad is loaded, it is stored in the cache and displayed. - -- **Theme & Format Aware Ads**: The `AdService` requests ads with theme-aware styling (`AdThemeStyle`) and the correct template size (`HeadlineImageStyle`). This ensures that ads match the user's current theme (light/dark mode) and the visual density of the surrounding content. - -This architecture ensures that the complex, stateful logic of ad loading is encapsulated at the widget level, keeping the BLoC layer clean and focused on managing the primary content. diff --git a/src/content/docs/mobile-client/features/authentication.mdx b/src/content/docs/mobile-client/features/authentication.mdx deleted file mode 100644 index 0fb1665..0000000 --- a/src/content/docs/mobile-client/features/authentication.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Authentication -description: Learn how user authentication is handled in the mobile client. ---- -import { Steps } from '@astrojs/starlight/components'; - -The mobile client features a robust authentication system that supports both email-based sign-in and anonymous guest access. This entire process is managed by the `AuthenticationBloc`. - -## The Authentication Flow - -The authentication flow is designed to be simple and secure, using a passwordless email and code verification system. It also includes user-friendly improvements for a smoother experience. - - -1. **Choose Sign-In Method** - - The user is first presented with the `AuthenticationPage`, which offers options to sign in with email or continue anonymously. This page's content adapts based on the context; for example, if an anonymous user is trying to access a feature that requires an account, it will display a prompt to "link" their account. - -2. **Request Code** - - If the user chooses email sign-in, they are navigated to the `RequestCodePage`. Here, they enter their email address. The `AuthenticationBloc` handles an `AuthenticationRequestSignInCodeRequested` event and calls the `AuthRepository` to send a verification code to the user's email. - -3. **Verify Code** - - After a code is sent, the user is taken to the `EmailCodeVerificationPage`. They enter the 6-digit code they received into an improved code entry field powered by the `pinput` widget. The `AuthenticationBloc` processes an `AuthenticationVerifyCodeRequested` event, which calls the `AuthRepository` to verify the code. - -4. **Authenticated State** - - Upon successful verification, the `AuthRepository` returns a new `User` object. The `AppBloc` listens for this change and updates its state to `authenticated`, granting the user access to protected features. The router's redirect logic then automatically navigates the user away from the authentication screens to the main app content. - - -## Anonymous Access - -The app also supports an anonymous sign-in flow. When the user chooses to continue anonymously, the `AuthenticationBloc` dispatches an `AuthenticationAnonymousSignInRequested` event. The `AuthRepository` creates a new anonymous user, and the `AppBloc` transitions to a special `anonymous` state. This allows guest users to browse content with certain limitations, and they can choose to link their account to a permanent email address at any time. - -## Security and UX Enhancements - -- **Request Cooldown**: To prevent abuse of the email service, a 60-second cooldown is enforced between sign-in code requests. The UI provides a visual countdown timer, informing the user when they can request a new code. -- **Enhanced Code Input**: The code verification screen uses the `pinput` widget to provide a more polished and user-friendly experience for entering the 6-digit code. - -## Core Components - -- **`AuthenticationBloc`**: Located in `lib/authentication/bloc/`, this BLoC orchestrates the entire authentication process. It listens to events from the UI, interacts with the `AuthRepository`, and emits states that reflect the current status of the authentication flow (e.g., `loading`, `failure`, `requestCodeSuccess`). - -- **`AuthRepository`**: A shared package that abstracts the data source for authentication. It makes the actual calls to either the in-memory client (in demo mode) or the API client. - -- **UI Pages**: Located in `lib/authentication/view/`, these widgets provide the user interface for each step of the flow. They dispatch events to the `AuthenticationBloc` and rebuild according to its state. diff --git a/src/content/docs/mobile-client/features/entity-details.mdx b/src/content/docs/mobile-client/features/entity-details.mdx deleted file mode 100644 index 02f2e53..0000000 --- a/src/content/docs/mobile-client/features/entity-details.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Entity Details -description: Learn how the app displays detailed pages for topics and sources. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Entity Details page is a versatile component designed to display a detailed view for content entities like **Topics** and **Sources**. It serves as a hub for a specific entity, showing its description and a feed of all related headlines. - -## Core Components - -- **`EntityDetailsBloc`**: The BLoC that powers this feature. It is responsible for fetching the primary entity's data (e.g., the `Topic` object) and then fetching a paginated list of `Headline` items that are associated with that entity. It also syncs with the `AccountBloc` to manage the "follow" status of the entity. - -- **`EntityDetailsPage`**: The main UI widget. It can be initialized in two ways: by passing a full entity object (like a `Topic` or `Source`) or by passing an `entityId` and `contentType`. The page displays the entity's details at the top and a scrollable list of related headlines below. - -## Key Functionalities - - - - This page is designed to be generic. The same `EntityDetailsPage` is used to display information for both Topics and Sources, reducing code duplication and ensuring a consistent user experience across different content types. - - - The page first loads the details of the entity itself. Once the entity is loaded, the `EntityDetailsBloc` begins fetching the associated headlines, with support for infinite scrolling to load more articles as the user scrolls down. - - - A prominent "follow" button allows users to follow or unfollow the displayed topic or source. This action is dispatched to the `AccountBloc`. The `EntityDetailsBloc` subscribes to state changes from the `AccountBloc` to reactively update the UI of the follow button. - - - The list of related headlines is not just a simple list; it's a fully integrated feed. The `FeedInjectorService` is used to dynamically insert ads and other content into the headline list, just like in the main headlines feed. - - diff --git a/src/content/docs/mobile-client/features/headline-details.mdx b/src/content/docs/mobile-client/features/headline-details.mdx deleted file mode 100644 index 0551dc8..0000000 --- a/src/content/docs/mobile-client/features/headline-details.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Headline Details -description: Learn how the mobile client displays individual articles and similar content. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Headline Details page provides an immersive view of a single news article. It is responsible for fetching and displaying the full content of a headline, as well as suggesting related articles to keep users engaged. - -## Core Components - -This feature is primarily managed by two BLoCs that work together to populate the page. - -- **`HeadlineDetailsBloc`**: This BLoC is responsible for the main content of the page. It handles fetching the full `Headline` object from the repository, either by its ID (`FetchHeadlineById`) or by receiving the full object directly (`HeadlineProvided`). It manages the loading, success, and failure states for the primary article. - -- **`SimilarHeadlinesBloc`**: Once the main headline is loaded, this BLoC is triggered to find and display a list of related articles. It dispatches a `FetchSimilarHeadlines` event, using the topic of the current headline to query the repository for other articles with the same topic, excluding the current one. - -- **`HeadlineDetailsPage`**: The main UI widget for this feature. It orchestrates the two BLoCs and builds the user interface, which includes the article's image, title, excerpt, and metadata. It also contains the logic for user actions like saving/unsaving an article and sharing it. - -## Key Functionalities - - - - The page can be loaded in two ways: by passing a full `Headline` object (e.g., from a list view) for an instant display, or by passing just a `headlineId`, which triggers the `HeadlineDetailsBloc` to fetch the full data from the repository. - - - The page provides users with key actions. They can save or unsave an article, which is handled by the `AccountBloc`. They can also share the article using the `share_plus` package, which provides a native sharing dialog. - - - Interactive metadata chips are displayed below the article image, showing the publication date, source, and topic. Tapping on the source or topic chip navigates the user to the respective `EntityDetailsPage` for that source or topic. - - - At the bottom of the page, a list of similar headlines is displayed to encourage further reading. This list is populated by the `SimilarHeadlinesBloc` and reuses the shared `HeadlineTile` widgets for a consistent look and feel. - - diff --git a/src/content/docs/mobile-client/features/headlines-feed.mdx b/src/content/docs/mobile-client/features/headlines-feed.mdx deleted file mode 100644 index 3e7f9d2..0000000 --- a/src/content/docs/mobile-client/features/headlines-feed.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Headlines Feed -description: Learn how the main news feed is managed, including filtering and dynamic content. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Headlines Feed is the core feature of the mobile client, providing users with a scrollable list of news articles. It is a sophisticated system that supports pagination, pull-to-refresh, complex filtering, and dynamic content injection. - -## Core Components - -The feed is managed by a collection of BLoCs that handle different aspects of its functionality. - -- **`HeadlinesFeedBloc`**: The central BLoC that manages the state of the main feed. It is responsible for fetching headlines from the `HeadlinesRepository`, handling pagination (`HeadlinesFeedFetchRequested`), and applying filters (`HeadlinesFeedFiltersApplied`). - -- **`FeedInjectorService`**: A crucial service that dynamically injects non-headline content, such as advertisements (`Ad`) and account-related calls-to-action (`FeedAction`), into the list of headlines. It uses business logic based on the user's status and remote configuration to determine where and when to place this content. - -- **Filter BLoCs**: A set of specialized BLoCs manage the state for the filter selection pages: - - `TopicsFilterBloc`: Fetches and manages the list of available topics for filtering. - - `SourcesFilterBloc`: Manages the complex logic for filtering by source, which also includes sub-filters for country and source type. - - `CountriesFilterBloc`: Fetches and manages the list of countries for filtering. - -## Key Functionalities - - - - The feed uses pagination to load headlines continuously as the user scrolls. The `_onScroll` listener in `HeadlinesFeedPage` detects when the user is near the bottom of the list and dispatches a `HeadlinesFeedFetchRequested` event to load the next page of content. - - - Users can pull down from the top of the feed to refresh the content. This action triggers a `HeadlinesFeedRefreshRequested` event, which re-fetches the first page of headlines with the currently active filters. - - - Users can tap the filter icon in the AppBar to open the `HeadlinesFilterPage`. This page allows them to apply filters based on topics and sources. A unique feature is the "Apply my followed items" checkbox, which automatically creates a filter based on the user's followed topics and sources. - - - The `FeedInjectorService` intelligently inserts ads and calls-to-action (e.g., "Link your account") into the feed. This logic is based on rules defined in the `RemoteConfig`, such as ad frequency per user role, ensuring a tailored experience. - - diff --git a/src/content/docs/mobile-client/features/index.mdx b/src/content/docs/mobile-client/features/index.mdx deleted file mode 100644 index 232c514..0000000 --- a/src/content/docs/mobile-client/features/index.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Features -description: Explore the key features of the Flutter News App Mobile Client. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The mobile client is packed with features designed for a modern, engaging news application. Explore the guides below to understand its core capabilities. - - - - Learn how the main news feed is managed, including filtering and dynamic content. - [Read more →](/docs/mobile-client/features/headlines-feed/) - - - Learn how the mobile client displays individual articles and similar content. - [Read more →](/docs/mobile-client/features/headline-details/) - - - Learn how the app displays detailed pages for topics and sources. - [Read more →](/docs/mobile-client/features/entity-details/) - - - Learn how the search feature allows users to find headlines, topics, and sources. - [Read more →](/docs/mobile-client/features/search/) - - - Learn how user authentication is handled in the mobile client. - [Read more →](/docs/mobile-client/features/authentication/) - - - Learn how users can manage their preferences, saved articles, and followed content. - [Read more →](/docs/mobile-client/features/account/) - - - Learn how users can customize the application's appearance, language, and feed display. - [Read more →](/docs/mobile-client/features/settings/) - - - Learn about the provider-agnostic ad system for monetization. - [Read more →](/docs/mobile-client/features/ad-system/) - - diff --git a/src/content/docs/mobile-client/features/search.mdx b/src/content/docs/mobile-client/features/search.mdx deleted file mode 100644 index bb661a8..0000000 --- a/src/content/docs/mobile-client/features/search.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Search -description: Learn how the search feature allows users to find headlines, topics, and sources. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Search feature provides a powerful tool for users to find content across the entire application. Users can search for specific headlines, discover new topics, or look up their favorite news sources, all from a single, unified interface. - -## Core Components - -- **`HeadlinesSearchBloc`**: This is the engine behind the search feature. It manages the state of the search page, handling everything from user input to fetching and paginating results. It is designed to be flexible, allowing it to query different data repositories based on the content type selected by the user. - -- **`HeadlinesSearchPage`**: The primary UI for the search feature. It contains the search bar, a dropdown to select the content type to search for (Headlines, Topics, or Sources), and the results list. - -## Key Functionalities - - - - A key feature of the search page is the ability to search across different types of content. A dropdown in the AppBar allows the user to switch between searching for **Headlines**, **Topics**, or **Sources**. The `HeadlinesSearchBloc` dynamically adjusts its query and the data repository it targets based on this selection. - - - The search is triggered when the user submits their query from the text field in the AppBar. The UI includes a clear button that appears as soon as the user starts typing, providing a smooth user experience. - - - For queries that return a large number of results, the search page supports infinite scrolling. As the user scrolls to the bottom of the results list, the `HeadlinesSearchBloc` fetches the next page of data, ensuring the app remains responsive and efficient. - - - The search results are displayed using context-appropriate widgets. Headlines are rendered using the shared `HeadlineTile` widgets, while Topics and Sources are displayed using their own dedicated item widgets (`TopicItemWidget`, `SourceItemWidget`), ensuring that each result is presented clearly and effectively. - - diff --git a/src/content/docs/mobile-client/features/settings.mdx b/src/content/docs/mobile-client/features/settings.mdx deleted file mode 100644 index 2aad505..0000000 --- a/src/content/docs/mobile-client/features/settings.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Settings -description: Learn how users can customize the application's appearance, language, and feed display. ---- -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Settings section provides users with granular control over their application experience, allowing them to tailor the appearance, language, and content display to their personal preferences. - -## Core Components - -- **`SettingsBloc`**: This BLoC is the central hub for all user-configurable settings. It is responsible for loading the `UserAppSettings` object for the current user from the repository. If no settings exist (e.g., for a new user), it creates a default set and persists them. It handles events for every individual setting change, updating the state and saving the changes back to the repository. - -- **`SettingsPage`**: The main entry point for the settings feature. It provides a menu of setting categories, such as Language, Appearance, and Feed Display. - -- **Sub-Pages**: The settings are organized into several dedicated sub-pages for clarity: - - `LanguageSettingsPage`: Allows the user to select their preferred language. - - `AppearanceSettingsPage`: A menu that leads to theme and font settings. - - `ThemeSettingsPage`: For choosing between light/dark/system themes and selecting an accent color. - - `FontSettingsPage`: For adjusting text size, font family, and font weight. - - `FeedSettingsPage`: For configuring how headlines are displayed in the feed (e.g., image style). - -## Key Functionalities - - - - All settings are managed through the `UserAppSettings` model and are persisted per-user via the `DataRepository`. When a user changes a setting, the `SettingsBloc` updates its state and immediately calls the repository to save the change, ensuring preferences are retained across sessions. - - - Users have extensive control over the app's look and feel. They can switch between light, dark, and system themes, choose from multiple accent colors, select different font families, adjust the global text size, and even change the font weight for better readability. - - - The `FeedSettingsPage` allows users to customize how headlines are presented in their feed. For example, they can choose between different image styles: a large image at the top, a small thumbnail, or a text-only view for a more compact layout. - - - When a setting is changed in the `SettingsBloc`, it also notifies the main `AppBloc` via an `AppSettingsRefreshed` event. This triggers the `AppBloc` to reload the settings and apply the changes globally, ensuring that the entire application UI instantly reflects the user's new preferences. - - diff --git a/src/content/docs/mobile-client/features/status-pages.mdx b/src/content/docs/mobile-client/features/status-pages.mdx deleted file mode 100644 index 1f8d163..0000000 --- a/src/content/docs/mobile-client/features/status-pages.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 'Feature: Status Pages' -description: Learn about the critical, app-wide status pages for maintenance and required updates. ---- -import { Card, CardGrid, Aside } from '@astrojs/starlight/components'; - -The mobile client includes a set of full-screen status pages designed to handle critical, app-wide states. These pages are a key part of the [application startup flow](/docs/mobile-client/architecture/routing) and are displayed *before* the main application UI and router are ever built. - -This mechanism is triggered by the `RemoteConfig` object fetched from the backend upon application startup. It allows administrators to communicate important information to all users or enforce mandatory updates. - - - - -## The Status Pages - - - - When the `isUnderMaintenance` flag in the `RemoteConfig` is set to `true`, the application will display the `MaintenancePage`. This page informs the user that the app is temporarily unavailable and prevents them from proceeding further. It's a crucial tool for performing server-side updates without disrupting users with a broken app. - - - If the `isLatestVersionOnly` flag is `true` in the `RemoteConfig`, the `UpdateRequiredPage` is shown. This page instructs the user that they must update to the latest version of the app to continue. It includes a button that links directly to the appropriate app store (Apple App Store or Google Play Store), using the URL also provided in the `RemoteConfig`. - - - This is the very first UI the user sees when a remote configuration check is required. The `StatusPage` handles two states: - - **Loading**: Displays a loading indicator while the app is fetching the remote config (`AppStatus.configFetching`). - - **Failure**: If the fetch fails, it shows an error message and a "Retry" button, allowing the user to attempt the connection again (`AppStatus.configFetchFailed`). - - \ No newline at end of file diff --git a/src/content/docs/mobile-client/guides/index.mdx b/src/content/docs/mobile-client/guides/index.mdx deleted file mode 100644 index cb57cf9..0000000 --- a/src/content/docs/mobile-client/guides/index.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Developer Guides -description: Practical guides for developers on theming, customization, and localization for the mobile client. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -This section provides practical, step-by-step guides for developers working on the mobile client. - - - - Learn how to customize the application's visual appearance. - [Read more →](/docs/mobile-client/guides/styling-and-theming/) - - - A guide to adding new languages and translations to the mobile client. - [Read more →](/docs/mobile-client/guides/localization/) - - diff --git a/src/content/docs/mobile-client/guides/localization.mdx b/src/content/docs/mobile-client/guides/localization.mdx deleted file mode 100644 index b57ab26..0000000 --- a/src/content/docs/mobile-client/guides/localization.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: 'Guide: Localization' -description: A guide to adding new languages and translations to the mobile client. ---- -import { Steps, Aside } from '@astrojs/starlight/components'; - -The mobile client is fully internationalized using Flutter's built-in localization support. This guide explains how to add new translation strings and support for new languages. - -### Localization Files - -All translation strings are stored in Application Resource Bundle (`.arb`) files located in the `lib/l10n/arb/` directory. - -- `app_en.arb`: Contains the English translations. This is the template file. -- `app_ar.arb`: Contains the Arabic translations. - -Each entry in an `.arb` file consists of a key, the translated string, and an optional description. - -```json title="lib/l10n/arb/app_en.arb" -{ - "@@locale": "en", - "accountPageTitle": "Account", - "@accountPageTitle": { - "description": "Title for the account page" - } -} -``` - -### How to Add a New Translation String - - -1. **Add the Key to the English Template** - - Open `lib/l10n/arb/app_en.arb` and add a new entry for your string. Provide a clear key and a helpful description. - - ```json - "myNewFeatureTitle": "My New Feature", - "@myNewFeatureTitle": { - "description": "Title for the new feature page" - } - ``` - -2. **Add Translations to Other Languages** - - Open the `.arb` file for each supported language (e.g., `app_ar.arb`) and add the corresponding translated string for the new key. - - ```json - "myNewFeatureTitle": "ميزتي الجديدة", - ``` - -3. **Generate Dart Code** - - Flutter's localization tool automatically generates Dart code from your `.arb` files. This process is usually triggered automatically when you save an `.arb` file if you are using a modern IDE with the Flutter extension. - - If you need to run it manually, execute the following command in your terminal: - ```bash - flutter gen-l10n - ``` - -4. **Use the String in Your UI** - - You can now access your new string in any widget that has a `BuildContext` using the generated `AppLocalizations` class. - - ```dart - import 'package:flutter_news_app_mobile_client_full_source_code/l10n/l10n.dart'; - - // ... inside a build method - Text(context.l10n.myNewFeatureTitle); - ``` - - - -### How to Add a New Language - -To add support for a new language, such as French: -1. Create a new file: `lib/l10n/arb/app_fr.arb`. -2. Set the locale at the top of the file: `"@@locale": "fr"`. -3. Copy all the keys from `app_en.arb` and provide the French translations. -4. Run `flutter gen-l10n` to update the generated code. -5. Finally, add the new language to the list of supported languages in `lib/app/view/app.dart`. diff --git a/src/content/docs/mobile-client/guides/styling-and-theming.mdx b/src/content/docs/mobile-client/guides/styling-and-theming.mdx deleted file mode 100644 index d0f18b6..0000000 --- a/src/content/docs/mobile-client/guides/styling-and-theming.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Guide: Styling & Theming' -description: Learn how to customize the application's visual appearance. ---- -import { Aside } from '@astrojs/starlight/components'; - -The visual appearance of the Mobile Client—including colors, fonts, and spacing—is managed centrally to ensure consistency with the Web Dashboard. This is achieved through a shared `ui_kit` package. - -Because this is a cross-application concern, the primary, hands-on guide for making theme customizations is located in our new **Architecture & Customization** section. This central guide walks you through the entire process, from taking ownership of the `ui_kit` package to seeing your changes reflected in both the mobile and web apps. - - - -This approach ensures that you learn the correct workflow for modifying shared code, which is the key to unlocking the full power of the toolkit. diff --git a/src/content/docs/web-dashboard/architecture/data-loading-strategy.mdx b/src/content/docs/web-dashboard/architecture/data-loading-strategy.mdx deleted file mode 100644 index 9590d86..0000000 --- a/src/content/docs/web-dashboard/architecture/data-loading-strategy.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Data Loading Strategy -description: An explanation of the pre-fetching strategy for dropdown data in the web dashboard. ---- -import { Aside } from '@astrojs/starlight/components'; - -A key architectural decision in the web dashboard is the strategy for loading data into selection fields, such as the `Country` and `Language` dropdowns found in the content creation and editing forms. - -### The Challenge: UI Component Limitations - -The dashboard uses the standard Flutter `DropdownButtonFormField` to ensure a consistent and native user experience. However, a known limitation of this widget is its lack of support for scroll detection or on-demand pagination. This makes it impossible to dynamically load more items as a user scrolls through a long list. - -### The Solution: Pre-Fetching with `ThrottledFetchingService` - -To provide a seamless user experience and work around this limitation, we've implemented a **pre-fetching strategy**. - -When a user navigates to a section that requires this data (like Content Management), the `ContentManagementBloc` dispatches an event to fetch the *entire* list of required items (e.g., all countries, all languages) in the background. - -This process is handled by the `ThrottledFetchingService`, which is designed to be efficient and respectful to the API: -- It fetches the first page of data to understand the total scope. -- It then fetches the remaining pages sequentially, with a small, built-in delay between each request to avoid overwhelming the server. - -### The User Experience - -This background fetching is designed to be as unobtrusive as possible. -- If a user opens a form before the data has finished loading, the relevant dropdown menu will be temporarily disabled. -- A helper text message, "Loading full list...", will appear below the dropdown to inform the user that the data is on its way. -- Once the fetch is complete, the dropdown automatically becomes active, populated with the full list of options. - -This approach represents a deliberate engineering tradeoff: we accept the cost of a larger initial data load in exchange for a smoother, more consistent user interface without the complexity of implementing custom dropdown components. diff --git a/src/content/docs/web-dashboard/architecture/index.mdx b/src/content/docs/web-dashboard/architecture/index.mdx deleted file mode 100644 index 95b7a15..0000000 --- a/src/content/docs/web-dashboard/architecture/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Architecture -description: An overview of the architectural patterns and structure of the Flutter web dashboard. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Flutter News App Web Dashboard is built upon a clean, scalable, and maintainable architecture that separates concerns into distinct layers. This approach, combined with the use of shared packages, ensures that the codebase is both robust and easy to extend. - - - - An explanation of how the BLoC pattern is used for state management. - [Read more →](/docs/web-dashboard/architecture/state-management/) - - - An explanation of how navigation and routing are handled using go_router. - [Read more →](/docs/web-dashboard/architecture/routing/) - - - An explanation of the pre-fetching strategy for dropdown data. - [Read more →](/docs/web-dashboard/architecture/data-loading-strategy/) - - diff --git a/src/content/docs/web-dashboard/architecture/routing.mdx b/src/content/docs/web-dashboard/architecture/routing.mdx deleted file mode 100644 index d59667e..0000000 --- a/src/content/docs/web-dashboard/architecture/routing.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Routing (go_router) -description: An explanation of how navigation and routing are handled in the web dashboard using go_router. ---- - -Navigation within the web dashboard is managed by the powerful [`go_router`](https://pub.dev/packages/go_router) package. This provides a robust, URL-based routing system that is essential for a web application. - -Our routing configuration is centralized in the `lib/router/` directory. - -### `StatefulShellRoute` for Persistent Navigation - -The main dashboard interface, which includes the top app bar and the side navigation rail, is built using a `StatefulShellRoute`. This is a specialized route type from `go_router` that is perfect for creating scaffolded UI with persistent navigation. - -It allows us to define several independent navigation "branches," one for each of our main sections: -- Dashboard -- Content Management -- App Configuration - -When a user navigates between these sections, `StatefulShellRoute` preserves the state of each branch, including the scroll position and any nested navigation. - -### Authentication and Redirects - -The router is tightly integrated with the `AppBloc` to handle authentication-based redirects automatically. - -- The `GoRouter` is configured with a `refreshListenable` that listens to changes in the authentication status from the `AppBloc`. -- A `redirect` function checks the user's authentication status on every navigation change. - - If an unauthenticated user tries to access any page other than the sign-in page, they are automatically redirected to `/authentication`. - - If an authenticated user tries to access the sign-in page, they are automatically redirected to the main `/dashboard`. - -This ensures that the application's routes are always protected and that users are guided to the correct screen based on their session status. - -### Named Routes - -To prevent the use of hardcoded URL strings and to make navigation more maintainable, we use **named routes**. All route paths and names are defined as constants in the `lib/router/routes.dart` file. - -When navigating, we use methods like `context.goNamed('routeName')` instead of `context.go('/some/path')`. This makes the code cleaner and less prone to errors if a URL path needs to be changed in the future. diff --git a/src/content/docs/web-dashboard/architecture/state-management.mdx b/src/content/docs/web-dashboard/architecture/state-management.mdx deleted file mode 100644 index 86f8998..0000000 --- a/src/content/docs/web-dashboard/architecture/state-management.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: State Management (BLoC) -description: An explanation of how the BLoC pattern is used for state management in the web dashboard. ---- - -State management in the web dashboard is handled predictably and robustly using the **BLoC (Business Logic Component)** pattern. This pattern helps to separate business logic from the UI, leading to a more organized, testable, and scalable application. - -We utilize two main categories of BLoCs: - -### 1. Global `AppBloc` - -The `AppBloc` is a high-level BLoC that is provided at the root of the application. It is responsible for managing global state that affects the entire application. Its key responsibilities include: - -- **Authentication Status:** It listens to the `authStateChanges` stream from the `AuthRepository` and holds the current authentication status (`authenticated`, `unauthenticated`). This is used by the router to handle redirects. -- **Current User:** It holds the `User` object for the currently authenticated user. -- **User App Settings:** It loads and holds the `UserAppSettings`, which includes the user's preferred theme, language, and other display preferences. This allows the entire UI to react instantly to changes made in the settings page. - -### 2. Feature-Specific BLoCs - -Each major feature or section of the dashboard has its own dedicated BLoC to manage its specific state. This keeps the logic for each feature encapsulated and independent. - -- **`DashboardBloc`:** Responsible for fetching and holding the dashboard summary statistics and the list of recent headlines. -- **`ContentManagementBloc`:** Manages the state for the three content tabs (Headlines, Topics, Sources), including loading, paginating, and archiving content. It is also responsible for pre-fetching and caching shared data like the full list of countries and languages, which are then consumed by the create/edit BLoCs. -- **`ArchivedHeadlinesBloc`, `ArchivedTopicsBloc`, `ArchivedSourcesBloc`:** Each of these BLoCs is responsible for managing the state of its respective archived content page, including loading, restoring, and permanently deleting items. -- **`AppConfigurationBloc`:** Manages the state of the remote configuration form, tracking user edits, handling save operations, and managing the "dirty" state of the form. -- **`AuthenticationBloc`:** Manages the state of the sign-in flow, such as handling loading states when a code is requested or verified. -- **`SettingsBloc`:** Manages the state of the settings page, loading the user's current settings and processing update events. -- **Create/Edit BLoCs:** Each create and edit page (e.g., `CreateHeadlineBloc`, `EditTopicBloc`) has its own BLoC to manage the state of the form fields, validation, and the submission process. - -### The Flow of Data - -The typical data flow for a feature follows this pattern: - -1. **UI Event:** A user interacts with a widget, which dispatches an `Event` to its corresponding BLoC (e.g., `LoadHeadlinesRequested`). -2. **BLoC Processes Event:** The BLoC receives the event, calls one or more methods on its injected `Repository` to fetch or update data. -3. **Repository Fetches Data:** The `Repository` communicates with the `DataClient` to get data from the API or in-memory source. -4. **BLoC Emits State:** Based on the result from the repository (success or failure), the BLoC emits a new `State` object. -5. **UI Rebuilds:** A `BlocBuilder` or `BlocListener` in the UI layer listens for state changes and rebuilds the relevant parts of the widget tree to reflect the new state. diff --git a/src/content/docs/web-dashboard/features/app-configuration.mdx b/src/content/docs/web-dashboard/features/app-configuration.mdx deleted file mode 100644 index 4453eea..0000000 --- a/src/content/docs/web-dashboard/features/app-configuration.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: 'Feature: App Configuration' -description: How to remotely manage the behavior and settings of the mobile application. ---- - -import { Aside } from '@astrojs/starlight/components'; - -The App Configuration section is a powerful feature that allows you to dynamically control the behavior of your live mobile application without needing to submit a new version to the app stores. - - - -The configuration is divided into three main areas: - -### Feed Settings - -This tab allows you to control settings related to the user's content feed. - -- **User Content Limits:** Define the maximum number of items (topics, sources) a user can follow and the maximum number of headlines they can save. These limits can be set independently for different user roles (Guest, Standard User, Premium User). -- **Feed Actions:** Control how often in-feed prompts (like "Rate the App" or "Follow Topics") are displayed to users, with separate settings for Guest and Standard users. - -### Advertisements - -This tab controls how ads are displayed within the mobile app, allowing you to fine-tune your monetization strategy. - -- **Ad Frequency:** Set how often an ad appears in the content feed (e.g., one ad every 10 headlines). -- **Ad Placement:** Define a minimum number of headlines that must appear before the first ad is shown. -- **Interstitial Ads:** Configure how many headlines a user must read before a full-screen interstitial ad is displayed. - -All ad settings can be configured independently for Guest, Standard, and Premium users. - -### General Settings - -This tab manages the overall operational status of the mobile app. - -- **Maintenance Mode:** You can remotely place the entire mobile app into maintenance mode, which will display a message to users indicating the app is temporarily unavailable. -- **Force Update:** Specify the latest required version of your app. If a user is on an older version, you can force them to update from the app store before they can continue using the app. You can also configure the iOS and Android app store URLs here. diff --git a/src/content/docs/web-dashboard/features/authentication.mdx b/src/content/docs/web-dashboard/features/authentication.mdx deleted file mode 100644 index 05045ea..0000000 --- a/src/content/docs/web-dashboard/features/authentication.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 'Feature: Authentication' -description: An overview of the secure sign-in process for the web dashboard. ---- - -The web dashboard is protected by a secure, modern authentication system designed for administrators and content publishers. - -### Passwordless Sign-In - -To enhance security and improve user experience, the dashboard uses a **passwordless, email-based sign-in flow**. This eliminates the need for users to remember a password. - -The process is simple: - -1. **Enter Email:** The user enters their registered email address. -2. **Receive Code:** The system sends a unique, single-use 6-digit verification code to that email address. -3. **Verify Code:** The user enters the code into the dashboard to complete the sign-in process. - -This method ensures that only users with access to the registered email account can gain access to the dashboard. - -### Role-Based Access - -The system is designed to work with the API server's role-based access control (RBAC). Only users who have been assigned an `admin` or `publisher` role in the `dashboardRole` field of their user profile will be able to successfully sign in. diff --git a/src/content/docs/web-dashboard/features/content-management.mdx b/src/content/docs/web-dashboard/features/content-management.mdx deleted file mode 100644 index 2620a33..0000000 --- a/src/content/docs/web-dashboard/features/content-management.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 'Feature: Content Management' -description: How to create, read, update, and delete your application content. ---- - -The Content Management section is where you can perform detailed CRUD (Create, Read, Update, Delete) operations on all your core content types. The section is organized into three tabs: - -- **Headlines:** Manage your individual news content. -- **Topics:** Manage the categories for your news content. -- **Sources:** Manage the news sources from which you gather content. - -### The Interface - -Each tab presents a data table displaying the existing content. From these tables, you can: - -- **View Content:** See a paginated list of all active items. -- **Edit Content:** Click on any item in the table to navigate to its dedicated edit page. -- **Archive Content:** Use the archive icon on any item to move it to the archive. This is a "soft delete" that preserves data integrity. -- **Create New Content:** Use the "+" button in the top app bar to navigate to the creation page for the currently active tab (e.g., "Create Headline"). -- **Manage Archived Content:** Use the "Archived Items" button in the top app bar to access a separate screen where you can view, restore, or permanently delete archived content. - -This consistent interface provides a predictable and efficient workflow for managing all aspects of your application's content. diff --git a/src/content/docs/web-dashboard/features/dashboard-overview.mdx b/src/content/docs/web-dashboard/features/dashboard-overview.mdx deleted file mode 100644 index e3a032e..0000000 --- a/src/content/docs/web-dashboard/features/dashboard-overview.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Feature: Dashboard Overview' -description: An explanation of the main dashboard screen, its analytics, and quick actions. ---- - -The Dashboard Overview is the main landing page after signing in. It provides a high-level summary of your content ecosystem and offers quick access to common tasks. - -### Summary Cards - -At the top of the page, you'll find several summary cards that display key statistics about your content library. These cards show the total count of: - -- **Headlines:** The total number of news articles in your database. -- **Topics:** The total number of defined content topics. -- **Sources:** The total number of news sources you have configured. - -These metrics give you an immediate understanding of the scale of your content operation. - -### Recent Headlines - -This card displays a list of the most recently created headlines, allowing you to quickly see the latest content added to the system. Each item shows the headline title and when it was created. You can click on any headline to navigate directly to its edit page. - -### Quick Actions - -The Quick Actions card provides convenient shortcuts to the most common content creation tasks, allowing you to: - -- **Create a new Headline** -- **Create a new Topic** -- **Create a new Source** - -This streamlines the content management workflow by putting essential actions right at your fingertips. diff --git a/src/content/docs/web-dashboard/features/index.mdx b/src/content/docs/web-dashboard/features/index.mdx deleted file mode 100644 index b4af530..0000000 --- a/src/content/docs/web-dashboard/features/index.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Features -description: Explore the key features and architecture of the Web Dashboard. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -The Web Dashboard is packed with features designed for administrators and content publishers. Explore the guides below to understand its core capabilities. - - - - An explanation of the main dashboard screen, its analytics, and quick actions. - [Read more →](/docs/web-dashboard/features/dashboard-overview/) - - - How to create, read, update, and delete your application content. - [Read more →](/docs/web-dashboard/features/content-management/) - - - How to remotely manage the behavior and settings of the mobile application. - [Read more →](/docs/web-dashboard/features/app-configuration/) - - - An overview of the secure sign-in process for the web dashboard. - [Read more →](/docs/web-dashboard/features/authentication/) - - diff --git a/src/content/docs/web-dashboard/guides/index.mdx b/src/content/docs/web-dashboard/guides/index.mdx deleted file mode 100644 index 81e6478..0000000 --- a/src/content/docs/web-dashboard/guides/index.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Developer Guides -description: Practical guides for developers on theming, customization, and localization for the web dashboard. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -This section provides practical, step-by-step guides for developers working on the web dashboard. - - - - A developer's guide to customizing the visual appearance of the web dashboard. - [Read more →](/docs/web-dashboard/guides/theming-and-customization/) - - - A guide to adding new languages and translations to the web client. - [Read more →](/docs/web-dashboard/guides/localization/) - - diff --git a/src/content/docs/web-dashboard/guides/localization.mdx b/src/content/docs/web-dashboard/guides/localization.mdx deleted file mode 100644 index 7b641b2..0000000 --- a/src/content/docs/web-dashboard/guides/localization.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: 'Guide: Localization' -description: A guide to adding new languages and translations to the web client. ---- -import { Steps, Aside } from '@astrojs/starlight/components'; - -The web client is fully internationalized using Flutter's built-in localization support. This guide explains how to add new translation strings and support for new languages. - -### Localization Files - -All translation strings are stored in Application Resource Bundle (`.arb`) files located in the `lib/l10n/arb/` directory. - -- `app_en.arb`: Contains the English translations. This is the template file. -- `app_ar.arb`: Contains the Arabic translations. - -Each entry in an `.arb` file consists of a key, the translated string, and an optional description. - -```json title="lib/l10n/arb/app_en.arb" -{ - "@@locale": "en", - "accountPageTitle": "Account", - "@accountPageTitle": { - "description": "Title for the account page" - } -} -``` - -### How to Add a New Translation String - - -1. **Add the Key to the English Template** - - Open `lib/l10n/arb/app_en.arb` and add a new entry for your string. Provide a clear key and a helpful description. - - ```json - "myNewFeatureTitle": "My New Feature", - "@myNewFeatureTitle": { - "description": "Title for the new feature page" - } - ``` - -2. **Add Translations to Other Languages** - - Open the `.arb` file for each supported language (e.g., `app_ar.arb`) and add the corresponding translated string for the new key. - - ```json - "myNewFeatureTitle": "ميزتي الجديدة", - ``` - -3. **Generate Dart Code** - - Flutter's localization tool automatically generates Dart code from your `.arb` files. This process is usually triggered automatically when you save an `.arb` file if you are using a modern IDE with the Flutter extension. - - If you need to run it manually, execute the following command in your terminal: - ```bash - flutter gen-l10n - ``` - -4. **Use the String in Your UI** - - You can now access your new string in any widget that has a `BuildContext` using the generated `AppLocalizations` class. - - ```dart - import 'package:flutter_news_app_web_dashboard_full_source_code/l10n/l10n.dart'; - - // ... inside a build method - Text(context.l10n.myNewFeatureTitle); - ``` - - - -### How to Add a New Language - -To add support for a new language, such as French: -1. Create a new file: `lib/l10n/arb/app_fr.arb`. -2. Set the locale at the top of the file: `"@@locale": "fr"`. -3. Copy all the keys from `app_en.arb` and provide the French translations. -4. Run `flutter gen-l10n` to update the generated code. -5. Finally, add the new language to the list of supported languages in `lib/app/view/app.dart`. diff --git a/src/content/docs/web-dashboard/guides/styling-and-theming.mdx b/src/content/docs/web-dashboard/guides/styling-and-theming.mdx deleted file mode 100644 index 8f6f9fb..0000000 --- a/src/content/docs/web-dashboard/guides/styling-and-theming.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Guide: Styling & Theming' -description: Learn how to customize the application's visual appearance. ---- -import { Aside } from '@astrojs/starlight/components'; - -The visual appearance of the Web Dashboard—including colors, fonts, and spacing—is managed centrally to ensure consistency with the Mobile Client. This is achieved through a shared `ui_kit` package. - -Because this is a cross-application concern, the primary, hands-on guide for making theme customizations is located in our new **Architecture & Customization** section. This central guide walks you through the entire process, from taking ownership of the `ui_kit` package to seeing your changes reflected in both the web and mobile apps. - - - -This approach ensures that you learn the correct workflow for modifying shared code, which is the key to unlocking the full power of the toolkit. diff --git a/src/content/docs/web-dashboard/index.mdx b/src/content/docs/web-dashboard/index.mdx index ab34400..3b6a3f7 100644 --- a/src/content/docs/web-dashboard/index.mdx +++ b/src/content/docs/web-dashboard/index.mdx @@ -16,20 +16,4 @@ The Web Dashboard is a comprehensive, production-ready web application built wit Learn how to deploy the web dashboard to a production environment. [Read more →](/docs/web-dashboard/deployment/) - - Explore the key features, from content management to remote app configuration. - [Read more →](/docs/web-dashboard/features/) - - - Understand the architecture, state management, and navigation patterns. - [Read more →](/docs/web-dashboard/architecture/) - - - Practical guides for developers on theming, customization, and localization. - [Read more →](/docs/web-dashboard/guides/) - - - User-focused manuals for administrators and publishers. - [Read more →](/docs/web-dashboard/manuals/) - diff --git a/src/content/docs/web-dashboard/manuals/configuring-the-app.mdx b/src/content/docs/web-dashboard/manuals/configuring-the-app.mdx deleted file mode 100644 index 11f6ac7..0000000 --- a/src/content/docs/web-dashboard/manuals/configuring-the-app.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Configuring the Mobile App -description: A user manual for remotely configuring the mobile app from the web dashboard. ---- - -import { Aside } from '@astrojs/starlight/components'; - -The web dashboard provides a powerful set of tools to remotely control the behavior and settings of your live mobile application. This allows you to make dynamic changes without needing to release a new version to the app stores. - - - -### Navigating to App Configuration - -1. After signing in, you will see a navigation menu on the left side of the screen. -2. Click on the **"App Configuration"** item in the menu. - -This will take you to the main configuration screen, which is organized into three tabs: **Feed**, **Advertisements**, and **General**. - -### How to Modify Configuration Settings - -The process for changing any setting is the same: - -1. **Navigate to the Correct Tab:** Select the tab that contains the settings you wish to modify. -2. **Change the Values:** Interact with the form fields (text inputs, dropdowns, switches) to set your desired new values. -3. **Save Your Changes:** After making all your desired changes, click the **"Save Changes"** button in the bottom navigation bar. A confirmation dialog will appear. Click **"Confirm Save"** to apply your changes to the live application. - -If you make a mistake, you can click the **"Discard Changes"** button to revert all fields to their last saved state. - -### Available Settings - -#### Feed Tab - -- **User Content Limits:** Control how many items (topics, sources) a user can follow and how many headlines they can save. You can set these limits independently for Guest, Standard, and Premium users. -- **Feed Actions:** Adjust how frequently in-feed prompts (like "Rate the App") are shown to Guest and Standard users. - -#### Advertisements Tab - -- **Ad Settings:** Fine-tune your monetization strategy by controlling ad frequency, placement, and when full-screen interstitial ads are shown. These can also be set independently for Guest, Standard, and Premium users. - -#### General Tab - -- **Maintenance Mode:** Enable this switch to put the mobile app into maintenance mode. Users will see a maintenance screen and will not be able to access the app's content. -- **Force App Update:** Specify the minimum required version of your app. If a user is on an older version, you can force them to update from the app store. You can also set the iOS and Android app store URLs here. diff --git a/src/content/docs/web-dashboard/manuals/index.mdx b/src/content/docs/web-dashboard/manuals/index.mdx deleted file mode 100644 index 9f16a19..0000000 --- a/src/content/docs/web-dashboard/manuals/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: User Manuals -description: User-focused manuals for administrators and publishers using the web dashboard. ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -This section provides user-focused manuals for administrators and publishers. - - - - A user manual for creating, editing, and deleting content in the web dashboard. - [Read more →](/docs/web-dashboard/manuals/managing-content/) - - - A user manual for remotely configuring the mobile app from the web dashboard. - [Read more →](/docs/web-dashboard/manuals/configuring-the-app/) - - - Learn how to change the primary administrator email address. - [Read more →](/docs/web-dashboard/manuals/managing-admin-account/) - - diff --git a/src/content/docs/web-dashboard/manuals/managing-admin-account.mdx b/src/content/docs/web-dashboard/manuals/managing-admin-account.mdx deleted file mode 100644 index 64997c6..0000000 --- a/src/content/docs/web-dashboard/manuals/managing-admin-account.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Managing Your Admin Account -description: Learn how to change the primary administrator email address for the application. ---- - -import { Aside } from '@astrojs/starlight/components'; - -As the primary administrator, you may need to change the email address associated with your admin account. For security reasons, this is not an operation that can be performed from within the dashboard itself. Instead, it is handled by a secure, server-level configuration change. - -This process ensures that only an individual with access to the server's deployment environment can make this critical change. - -### How to Change the Administrator Email - -To set or change the administrator email, you must modify the environment variables in your API server's hosting environment. - -1. **Set the `OVERRIDE_ADMIN_EMAIL` Variable** - - In your hosting provider's configuration panel (or in your local `.env` file), set the `OVERRIDE_ADMIN_EMAIL` variable to the email address you want to use for the administrator account. - - ```env - OVERRIDE_ADMIN_EMAIL="new-admin@example.com" - ``` - -2. **Restart the API Server** - - After setting the variable, restart your API server. The system will automatically update the administrator account on startup. - - diff --git a/src/content/docs/web-dashboard/manuals/managing-content.mdx b/src/content/docs/web-dashboard/manuals/managing-content.mdx deleted file mode 100644 index 0270c4a..0000000 --- a/src/content/docs/web-dashboard/manuals/managing-content.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Managing Content -description: A user manual for creating, editing, and deleting content in the web dashboard. ---- - -import { Steps } from '@astrojs/starlight/components'; - -This manual provides a step-by-step guide for administrators and publishers on how to manage the content of the news application using the web dashboard. - -### Navigating to Content Management - -1. After signing in, you will see a navigation menu on the left side of the screen. -2. Click on the **"Content Management"** item in the menu. - -This will take you to the main content management screen, which is organized into three tabs: **Headlines**, **Topics**, and **Sources**. - -### How to Create New Content (Headlines, Topics, Sources) - -The process for creating a new headline, topic, or source is very similar. - - -1. **Select the Correct Tab** - - Click on the tab corresponding to the type of content you want to create (e.g., click the "Topics" tab to create a new topic). - -2. **Click the "Add" Button** - - In the top right corner of the app bar, click the **"+"** icon. This will take you to the "Create" page for that content type. - -3. **Fill Out the Form** - - Complete all the required fields in the form. Each field will have a descriptive label (e.g., "Topic Name," "Description"). - -4. **Save Your Changes** - - Once you have filled out the form, click the **Save** icon in the top right corner of the app bar. - - - -Your new content item will be created and will now appear in the data table. - -### How to Edit Existing Content - - -1. **Find the Content Item** - - Navigate to the correct tab ("Headlines," "Topics," or "Sources") and find the item you wish to edit in the data table. You can use the pagination controls at the bottom of the table if you have many items. - -2. **Open the Edit Page** - - Click anywhere on the row of the item you want to edit. This will take you to the "Edit" page for that specific item, with all its current data pre-filled in the form. - -3. **Make Your Changes** - - Update the fields in the form as needed. - -4. **Save Your Changes** - - Click the **Save** icon in the top right corner of the app bar to apply your changes. - - - -### How to Archive Content - -Archiving content is a "soft delete". It removes an item from the main lists but keeps it in the system for data integrity. This is the standard way to remove content. - - -1. **Find the Content Item** - - Navigate to the correct tab ("Headlines," "Topics," or "Sources") and find the item you wish to archive in the data table. - -2. **Click the Archive Icon** - - On the far right of the item's row, you will see a set of action icons. Click the **archive** icon. - - - -The item will be immediately moved to the archive. - -### Managing Archived Content - -The archive pages allow you to review, restore, or permanently delete content. - - -1. **Access the Archive** - - First, select the tab for the content type you're interested in (e.g., "Headlines"). Then, click the **"Archived Items"** icon (looks like a box) in the top right corner of the app bar. This will take you to the archive page for that content type. - -2. **Restore an Item** - - To restore an item, find it in the archived list and click the **restore** icon. The item will be moved back to the main content list with an "active" status. - -3. **Permanently Delete a Headline** - - *Only headlines can be permanently deleted, and only from the archive page.* This is a final, irreversible action. - - To delete a headline forever, find it in the archived headlines list and click the **delete forever** icon (a trash can). - - For safety, a snackbar will appear for 5 seconds with an **"Undo"** button, giving you a chance to reverse the deletion before it becomes permanent. -