Merge pull request #6 from flutter-news-app-full-source-code/enhance_dashboard_docs

Enhance dashboard docs

Author: fulleni

astro.config.mjs

@@ -90,10 +90,35 @@ export default defineConfig({
 							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: 'Content Management', link: '/web-dashboard/features/content-management' },
-								{ label: 'Dashboard Overview', link: '/web-dashboard/features/dashboard-overview' },
+							],
+						},
+						{
+							label: 'Architecture',
+							collapsed: true,
+							items: [
+								{ label: 'Overview', link: '/web-dashboard/architecture/overview' },
+								{ label: 'State Management (BLoC)', link: '/web-dashboard/architecture/state-management' },
+								{ label: 'Routing (go_router)', link: '/web-dashboard/architecture/routing' },
+							],
+						},
+						{
+							label: 'Guides',
+							collapsed: true,
+							items: [
+								{ label: 'Theming & Customization', link: '/web-dashboard/guides/theming-and-customization' },
+								{ label: 'Adding a New Language', link: '/web-dashboard/guides/adding-a-new-language' },
+							],
+						},
+						{
+							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: 'Deployment', link: '/web-dashboard/deployment' },

src/content/docs/web-dashboard/architecture/overview.mdx

@@ -0,0 +1,30 @@
+---
+title: Architecture Overview
+description: An overview of the architectural patterns and structure of the Flutter web dashboard.
+---
+
+import { Aside } 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.
+
+### Layered Architecture
+
+The dashboard follows a classic layered architecture, ensuring a clear separation of responsibilities:
+
+1.  **Presentation Layer (UI):** This is the user-facing layer, built with Flutter widgets. It is responsible for displaying the UI and capturing user input. It is kept as "dumb" as possible, meaning it contains minimal logic and simply reflects the state provided by the Business Logic Layer.
+
+2.  **Business Logic Layer (BLoC):** This layer contains the application's state management and business rules. We use the **BLoC (Business Logic Component)** pattern to manage the flow of information from user events to UI states. Feature-specific BLoCs (e.g., `ContentManagementBloc`, `DashboardBloc`) orchestrate data from the Repository Layer and emit states for the UI to consume.
+
+3.  **Repository Layer:** This layer abstracts the origin of the data. It provides a clean, simple API for the Business Logic Layer to access data, without needing to know whether the data is coming from a remote API or a local in-memory source. This is a key part of our strategy for testability and environment flexibility.
+
+4.  **Data Layer (Clients):** This is the lowest layer, responsible for the actual data retrieval. It consists of `Client` implementations that communicate with external sources. For the dashboard, this means either an `HttpDataClient` that makes requests to the API server or an `InMemoryDataClient` used for the demo environment.
+
+<Aside>
+The Repository and Data layers are not implemented directly within the dashboard. Instead, the dashboard consumes them as shared packages, which are used across the entire ecosystem (including the mobile app and API server).
+</Aside>
+
+### Core Principles
+
+-   **Dependency Injection:** Repositories and other services are provided to the widget tree using `RepositoryProvider` and `BlocProvider`. This decouples our components and makes them highly testable.
+-   **Immutability:** All data models and BLoC states are immutable, which leads to more predictable state management and reduces the risk of side effects.
+-   **Shared Packages:** The dashboard leverages a suite of shared packages for core functionality (e.g., `core`, `data_repository`, `auth_repository`, `ui_kit`). This promotes code reuse and consistency across the entire project ecosystem.

src/content/docs/web-dashboard/architecture/routing.mdx

@@ -0,0 +1,36 @@
+---
+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.

src/content/docs/web-dashboard/architecture/state-management.mdx

@@ -0,0 +1,37 @@
+---
+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 deleting content.
+-   **`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.

src/content/docs/web-dashboard/deployment.mdx

@@ -5,7 +5,11 @@ description: A guide to building and deploying the Flutter web dashboard to a pr
 
 import { Steps, Aside } from '@astrojs/starlight/components';
 
-This guide covers the essential steps for deploying the Flutter News App Web Dashboard to a production hosting service.
+This guide outlines the process for deploying the Flutter News App Web Dashboard.
+
+<Aside>
+To ensure you have the most reliable and up-to-date instructions, this guide will direct you to the official Flutter documentation. The process of building and deploying a Flutter web app is well-documented by the Flutter team, and their guide is the definitive resource for this task.
+</Aside>
 
 <Steps>
 1.  **Configure for Production**
@@ -25,51 +29,13 @@ This guide covers the essential steps for deploying the Flutter News App Web Das
     Ensure that the `baseUrl` for the `production` environment in `lib/app/config/app_config.dart` points to the correct URL of your deployed [API Server](/docs/api-server/deployment/).
     </Aside>
 
-2.  **Build the Web Application**
-
-    Next, create a production-optimized build of the Flutter web app. This compiles the Dart code to JavaScript and bundles all necessary assets for web deployment.
-
-    Run the following command from the root of your web dashboard project:
-    ```bash
-    flutter build web
-    ```
-    This will generate a `build/web` directory containing all the static files for your web application.
-
-3.  **Choose a Hosting Provider**
-
-    You can deploy the contents of the `build/web` directory to any hosting service that supports static websites. Popular and easy-to-use choices include:
-
-    -   [Firebase Hosting](https://firebase.google.com/docs/hosting)
-    -   [Vercel](https://vercel.com/)
-    -   [Netlify](https://www.netlify.com/for/web-applications/)
-    -   [GitHub Pages](https://docs.github.com/en/pages)
-
-4.  **Deploy the Application**
+2.  **Follow the Official Flutter Deployment Guide**
 
-    Follow the deployment instructions for your chosen hosting provider. The general process involves:
+    The Flutter team provides a comprehensive guide that covers everything you need to know about building and deploying a Flutter web application. This includes compiling your Dart code to JavaScript and deploying the output to various hosting services.
 
-    -   Initializing the hosting service in your project directory.
-    -   Specifying the `build/web` directory as the public or publish directory.
-    -   Running the provider's deploy command from your terminal.
-
-    For example, if you were using Firebase Hosting, the commands would look something like this:
-
-    ```bash
-    # Install Firebase CLI (if you haven't already)
-    npm install -g firebase-tools
-
-    # Log in to Firebase
-    firebase login
-
-    # Initialize Firebase in your project
-    firebase init hosting
-
-    # When prompted, set the public directory to "build/web"
-
-    # Deploy to Firebase Hosting
-    firebase deploy
-    ```
+    Please follow the official guide here:
+    **[Build and release a web app](https://flutter.dev/docs/deployment/web)**
 
-    Once the deployment is complete, your web dashboard will be live at the URL provided by your hosting service.
+    This guide will walk you through the `flutter build web` command and provide best practices for hosting the contents of the generated `build/web` directory.
 
 </Steps>

src/content/docs/web-dashboard/guides/adding-a-new-language.mdx

@@ -0,0 +1,73 @@
+---
+title: Adding a New Language
+description: A guide for developers on how to add a new language for localization.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+The web dashboard is built with localization in mind, making it straightforward to add support for new languages. The process involves creating a new `.arb` file and updating a few places in the code.
+
+<Steps>
+1.  **Create a New `.arb` File**
+
+    Application strings are stored in Application Resource Bundle (`.arb`) files located in `lib/l10n/arb/`.
+
+    -   Duplicate the `app_en.arb` file.
+    -   Rename the new file to `app_<language_code>.arb`, where `<language_code>` is the two-letter ISO 639-1 code for the new language (e.g., `app_es.arb` for Spanish).
+    -   Translate all the string values in the new file.
+
+2.  **Update `l10n.yaml`**
+
+    The `l10n.yaml` file in the root of the project configures the code generation for localization.
+
+    -   Open `l10n.yaml`.
+    -   Add your new `.arb` file to the list.
+
+    ```yaml title="l10n.yaml"
+    arb-dir: lib/l10n/arb
+    template-arb-file: app_en.arb
+    output-localization-file: app_localizations.dart
+    ```
+
+3.  **Run Code Generation**
+
+    Flutter's localization tool will automatically generate the necessary Dart code to support the new language.
+
+    Run the following command in your terminal:
+    ```bash
+    flutter gen-l10n
+    ```
+
+4.  **Update the Settings Page**
+
+    To make the new language selectable by the user, you need to add it to the settings page UI.
+
+    -   Open `lib/settings/view/settings_page.dart`.
+    -   Locate the `_LanguageSelectionList` widget.
+    -   Add the new language code to the `_supportedLanguages` list.
+    -   Add a case to the `_getLanguageName` method to provide a display name for the new language.
+
+    ```dart title="lib/settings/view/settings_page.dart"
+    class _LanguageSelectionList extends StatelessWidget {
+      // ...
+
+      String _getLanguageName(AppLanguage language, AppLocalizations l10n) {
+        switch (language) {
+          case 'en':
+            return l10n.englishLanguage;
+          case 'ar':
+            return l10n.arabicLanguage;
+          // Add your new language here
+          case 'es':
+            return 'Español'; // This should come from your .arb file
+        }
+      }
+
+      // Add your new language code here
+      static const List<AppLanguage> _supportedLanguages = ['en', 'ar', 'es'];
+    }
+    ```
+
+</Steps>
+
+After completing these steps, the new language will be fully integrated into the web dashboard.

src/content/docs/web-dashboard/guides/theming-and-customization.mdx

@@ -0,0 +1,48 @@
+---
+title: Theming & Customization
+description: A developer's guide to customizing the visual appearance of the web dashboard.
+---
+
+The web dashboard's visual theme is managed through a centralized and flexible system, making it easy to customize the appearance to match your brand. The theming is handled within the shared `ui_kit` package, primarily in the `packages/ui-kit/lib/src/theme/app_theme.dart` file.
+
+### Theming with `flex_color_scheme`
+
+We use the powerful [`flex_color_scheme`](https://pub.dev/packages/flex_color_scheme) package to create and manage our `ThemeData`. This package simplifies the process of creating consistent and beautiful color schemes and component themes.
+
+The core of the theming is in the `lightTheme()` and `darkTheme()` functions in `app_theme.dart`.
+
+### Customizing Colors
+
+You can change the entire color palette of the dashboard by modifying the `FlexScheme` used.
+
+1.  **Open `app.dart`:** Navigate to `apps/flutter-news-app-web-dashboard-full-source-code/lib/app/view/app.dart`.
+2.  **Locate the Theme Generation:** Find the `build` method of the `_AppViewState` widget.
+3.  **Change the `FlexScheme`:** The `accentTheme` from the user's settings is converted to a `FlexScheme`. You can change which `AppAccentTheme` enum value is the default in the `AppBloc` or modify the `toFlexScheme` extension to use different schemes from the `FlexScheme` enum.
+
+    ```dart title="lib/app/view/app.dart"
+    extension AppAccentThemeExtension on AppAccentTheme {
+      FlexScheme get toFlexScheme {
+        switch (this) {
+          case AppAccentTheme.defaultBlue:
+            // Change this to another FlexScheme, e.g., FlexScheme.deepPurple
+            return FlexScheme.materialHc; 
+          case AppAccentTheme.newsRed:
+            return FlexScheme.redWine;
+          case AppAccentTheme.graphiteGray:
+            return FlexScheme.outerSpace;
+        }
+      }
+    }
+    ```
+
+### Customizing Fonts
+
+The application uses Google Fonts by default. You can change the default font or add new ones.
+
+1.  **Open `app_theme.dart`:** Navigate to `packages/ui-kit/lib/src/theme/app_theme.dart`.
+2.  **Modify `_getGoogleFontTextTheme`:** This function maps a font family name (string) to a `GoogleFonts` text theme function. You can add new cases for other fonts available in the `google_fonts` package.
+3.  **Update `_supportedFontFamilies`:** In `apps/flutter-news-app-web-dashboard-full-source-code/lib/settings/view/settings_page.dart`, add the new font family name to the `_supportedFontFamilies` list to make it available in the user's settings.
+
+### Customizing Spacing
+
+Consistent spacing is managed by the `AppSpacing` class in `packages/ui-kit/lib/src/constants/app_spacing.dart`. If you need to adjust the global spacing values (e.g., change the small spacing from `8.0` to `10.0`), you can do so in this file, and the changes will be reflected across the entire application.