Merge pull request #23 from flutter-news-app-full-source-code/docs/fix

Docs/fix

Author: fulleni

README.md

@@ -9,66 +9,4 @@
   <a href="https://github.com/flutter-news-app-full-source-code"><img src="https://img.shields.io/badge/MAIN_PROJECT-BROWSE-purple?style=for-the-badge" alt="Main Project: Browse"></a>
 </p>
 
-This repository contains the source code for the official documentation website for the [**Flutter News App Full Source Code Toolkit**](https://github.com/flutter-news-app-full-source-code). Built with [Astro](https://astro.build/), this site provides comprehensive guides, tutorials, and API references to help developers understand, set up, customize, and deploy the entire toolkit. It serves as a central knowledge base, ensuring that all components—the Flutter mobile app, web dashboard, and Dart Frog backend API—are well-documented and easy to navigate.
-
-## ⭐ Documentation Overview: Your Guide to the Toolkit
-
-This documentation website offers a structured and detailed overview of the Flutter News App Full Source Code Toolkit.
-
-<details>
-<summary><strong>📚 Content & Structure</strong></summary>
-
-### 📖 Comprehensive Guides
-- **Getting Started:** Essential information for setting up your development environment, understanding the core philosophy, and architectural overview.
-- **Mobile Client:** Detailed guides for the Flutter mobile application, covering architecture, features, deployment (Android/iOS), and customization.
-- **Web Dashboard:** Comprehensive documentation for the Flutter web dashboard, including architecture, features, deployment, and management manuals.
-- **API Server:** In-depth information on the Dart Frog backend API, its architecture, features (authentication, data management, email service), deployment, and configuration.
-- **Customization:** Guides on branding, theming, and extending the toolkit to fit your specific needs.
-
-### 🛠️ Technical Foundation
-- **Built with Astro:** The documentation site itself is powered by [Astro](https://astro.build/), a modern static site generator, ensuring fast performance and maintainability.
-- **Clear Navigation:** Organized into logical sections and pages for easy discovery of information.
-
-> **💡 Your Advantage:** This documentation provides a clear, organized, and comprehensive resource for the Flutter News App Toolkit. It simplifies the learning curve, accelerates development by offering detailed setup and customization guides, and ensures you have all the information needed to successfully build and deploy your news application.
-
-</details>
-
-## 🚀 Getting Started: Running Locally
-
-To preview changes or contribute to the documentation, you can run a local development server.
-
-1.  **Prerequisites:**
-    *   Ensure [Node.js](https://nodejs.org/) (LTS version) is installed on your system.
-
-2.  **Clone the repository:**
-    ```bash
-    git clone https://github.com/flutter-news-app-full-source-code/docs.git
-    cd docs
-    ```
-
-3.  **Install dependencies:**
-    ```bash
-    npm install
-    ```
-
-4.  **Start the development server:**
-    ```bash
-    npm run dev
-    ```
-    The site will now be available at `http://localhost:4321`. It will automatically reload as you make changes to the content.
-
-## 📝 License
-
-This repository uses a dual-licensing model to provide clarity for different types of content.
-
-#### Documentation Content
-
-All prose, tutorials, and narrative content within this documentation are licensed under the **[Creative Commons Attribution 4.0 International License (CC BY 4.0)](./LICENSE)**. This allows our guides to be openly shared and improved by the community.
-
-#### Code Snippets
-
-All code examples and snippets embedded within the documentation are a separate matter. Unless otherwise specified, they are dedicated to the **[Public Domain via CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/)**.
-
-This means you are free to copy, paste, modify, and use these illustrative snippets in your own applications without restriction.
-
-This dual-licensing approach ensures our documentation is open and shareable, while protecting the commercial value of the underlying source code product, which is governed by our **[Lifetime Developer License](https://github.com/flutter-news-app-full-source-code/.github/blob/main/LIFETIME_DEVELOPER_LICENSE.md)**.
+This repository contains the source code for the official documentation website for the [**Flutter News App Full Source Code Toolkit**](https://github.com/flutter-news-app-full-source-code).

src/content/docs/api-server/local-setup.mdx

@@ -18,14 +18,13 @@ This guide will walk you through setting up the API server in a local developmen
         dart pub global activate dart_frog_cli
         ```
 
-2.  **Clone the Repository**
+2.  **Download the Latest Release**
 
-    If you haven't already, clone the repository to your local machine.
+    Download the source code of the latest release from the GitHub releases page for the API Server:
 
-    ```bash
-    git clone https://github.com/flutter-news-app-full-source-code/flutter-news-app-api-server-full-source-code.git
-    cd flutter-news-app-api-server-full-source-code
-    ```
+    -   **API Server:** [https://github.com/flutter-news-app-full-source-code/flutter-news-app-api-server-full-source-code/releases/latest](https://github.com/flutter-news-app-full-source-code/flutter-news-app-api-server-full-source-code/releases/latest)
+
+    After downloading and extracting the archive, navigate into the project directory.
 
 3.  **Set Up Local Database**
 
@@ -62,13 +61,4 @@ This guide will walk you through setting up the API server in a local developmen
     The API will now be running and available at `http://localhost:8080`.
     </Aside>
 
-7.  **Automatic Database Seeding**
-
-    On its first startup, the server automatically connects to your MongoDB database and seeds it with initial data (countries, topics, users, etc.). This process is idempotent, meaning you can safely restart the server multiple times without creating duplicate data.
-
-    <Aside type="tip">
-    For more details on how this works, see the [Understand Database Seeding](/docs/api-server/architecture/data-seeding-and-fixtures) guide.
-    </Aside>
-
-
 </Steps>

src/content/docs/development-environment-setup.mdx

@@ -0,0 +1,60 @@
+---
+title: Connecting to a Local API from a Physical Device
+description: A guide to configuring the development environment to test the mobile app on a physical device with a local API server.
+---
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+This guide explains how to connect the mobile client running on a physical device to an API server running on your local machine.
+
+### The `localhost` Challenge
+
+When the API server runs locally, it is accessible at `http://localhost:8080` on your computer. However, a physical mobile device connected to the same network cannot access your computer using the `localhost` address, as `localhost` refers to the device itself.
+
+To resolve this, your local API server must be made accessible over the network. A tunneling service like **ngrok** can accomplish this by creating a secure public URL that forwards traffic to your local server.
+
+<Aside>
+The use of tunneling services is intended for development and testing purposes only and is not a substitute for a properly deployed production environment.
+</Aside>
+
+### Configuration Steps
+
+<Steps>
+1.  **Start Your Local API Server**
+
+    Ensure your API server is running locally on the designated port.
+    -   See the [API Server Local Setup Guide](/docs/api-server/local-setup/) for instructions.
+
+2.  **Install and Run ngrok**
+
+    You will need to install `ngrok` and use it to expose your local server's port (e.g., `8080`). For detailed instructions on installation and usage, please refer to the official documentation.
+
+    -   **Official Guide:** [ngrok Documentation](https://ngrok.com/docs)
+
+    Once installed, run the following command to expose your local server:
+    ```bash
+    ngrok http 8080
+    ```
+    ngrok will provide a public forwarding URL (e.g., `https://....ngrok-free.app`).
+
+3.  **Set the Development Environment**
+
+    -   Open the file `lib/main.dart`.
+    -   Locate the `appEnvironment` constant.
+    -   Set its value to `AppEnvironment.development`.
+
+    ```dart title="lib/main.dart"
+    // Use `AppEnvironment.development` to connect to a live backend API.
+    const appEnvironment = AppEnvironment.development; 
+    ```
+
+4.  **Verify the API Base URL**
+
+    -   Open the file `lib/app/config/app_config.dart`.
+    -   Ensure that the `baseUrl` for the `development` case points to the ngrok forwarding URL for your local API server.
+
+
+5.  **Run the Application in Development Mode**
+
+    With the configuration updated, you can now run the application on your physical device in `development` mode, and it will successfully connect to your local API server.
+
+</Steps>

src/content/docs/mobile-client/deployment.mdx

@@ -11,7 +11,6 @@ To ensure you have the most reliable and up-to-date instructions, this guide foc
 </Aside>
 
 ### Pre-Deployment Configuration
-
 Before you can build the app for production, you must configure it to connect to your live API server.
 
 <Steps>
@@ -31,6 +30,35 @@ Before you can build the app for production, you must configure it to connect to
     -   Open the file `lib/app/config/app_config.dart`.
     -   Ensure that the `baseUrl` for the `production` case points to the correct URL of your deployed [API Server](/docs/api-server/deployment/).
 
+3.  **Configure App Icons**
+
+    The project uses `flutter_launcher_icons` to generate app icons. You will need to update the configuration in `pubspec.yaml` to use your own icon assets.
+
+    -   Open `pubspec.yaml`.
+    -   Locate the `flutter_launcher_icons` section.
+    -   Update the `image_path` to point to your desired icon image.
+    -   After updating, run the following command to generate the new icons:
+        ```bash
+        flutter pub run flutter_launcher_icons:main
+        ```
+    <Aside type="tip">
+    For more details, refer to the [flutter_launcher_icons documentation](https://pub.dev/packages/flutter_launcher_icons).
+    </Aside>
+
+4.  **Configure Native Splash Screen**
+
+    The project uses `flutter_native_splash` for native splash screens. You will need to update the configuration in `pubspec.yaml` to use your own splash screen assets and colors.
+
+    -   Open `pubspec.yaml`.
+    -   Locate the `flutter_native_splash` section.
+    -   Update `color`, `color_dark`, `image`, and `image_dark` to match your branding.
+    -   After updating, run the following command to generate the new splash screens:
+        ```bash
+        flutter pub run flutter_native_splash:create
+        ```
+    <Aside type="tip">
+    For more details, refer to the [flutter_native_splash documentation](https://pub.dev/packages/flutter_native_splash).
+    </Aside>
 </Steps>
 
 ### Building and Releasing

src/content/docs/mobile-client/local-setup.mdx

@@ -13,14 +13,13 @@ This guide will walk you through setting up and running the Flutter News App Mob
 
     -   **Flutter SDK:** Please follow the [Official Flutter Installation Guide](https://flutter.dev/docs/get-started/install) for your specific operating system.
 
-2.  **Clone the Repository**
+2.  **Download the Latest Release**
 
-    Open your terminal and clone the mobile client repository:
+    Download the source code of the latest release from the GitHub releases page for the Mobile Client:
 
-    ```bash
-    git clone https://github.com/flutter-news-app-full-source-code/flutter-news-app-mobile-client-full-source-code.git
-    cd flutter-news-app-mobile-client-full-source-code
-    ```
+    -   **Mobile Client:** [https://github.com/flutter-news-app-full-source-code/flutter-news-app-mobile-client-full-source-code/releases/latest](https://github.com/flutter-news-app-full-source-code/flutter-news-app-mobile-client-full-source-code/releases/latest)
+
+    After downloading and extracting the archive, navigate into the project directory.
 
 3.  **Install Dependencies**
 
@@ -52,6 +51,10 @@ This guide will walk you through setting up and running the Flutter News App Mob
     For the `development` environment, you must have the [API Server running locally](/docs/api-server/local-setup/) first.
     </Aside>
 
+    <Aside type="note">
+    To connect to your local API server from a physical mobile device, additional configuration is required. Please see the [Connecting to a Local API from a Physical Device](/docs/development-environment-setup/) guide.
+    </Aside>
+
 5.  **Run the Application**
 
     Start the Flutter development server. Ensure you have a simulator/emulator running or a physical device connected.

src/content/docs/web-dashboard/local-setup.mdx

@@ -14,14 +14,13 @@ This guide will walk you through setting up and running the Flutter News App Web
 
     -   **Flutter SDK:** Please follow the [Official Flutter Installation Guide](https://flutter.dev/docs/get-started/install) for your specific operating system.
 
-2.  **Clone the Repository**
+2.  **Download the Latest Release**
 
-    Open your terminal and clone the web dashboard repository:
+    Download the source code of the latest release from the GitHub releases page for the Web Dashboard:
 
-    ```bash
-    git clone https://github.com/flutter-news-app-full-source-code/flutter-news-app-web-dashboard-full-source-code.git
-    cd flutter-news-app-web-dashboard-full-source-code
-    ```
+    -   **Web Dashboard:** [https://github.com/flutter-news-app-full-source-code/flutter-news-app-web-dashboard-full-source-code/releases/latest](https://github.com/flutter-news-app-full-source-code/flutter-news-app-web-dashboard-full-source-code/releases/latest)
+
+    After downloading and extracting the archive, navigate into the project directory.
 
 3.  **Install Dependencies**
 
@@ -53,6 +52,10 @@ This guide will walk you through setting up and running the Flutter News App Web
     For the `development` environment, you must have the [API Server running locally](/docs/api-server/local-setup/) first.
     </Aside>
 
+    <Aside type="note">
+    To connect to your local API server from a physical mobile device, additional configuration is required. Please see the [Connecting to a Local API from a Physical Device](/docs/development-environment-setup/) guide.
+    </Aside>
+
 5.  **Run the Development Server**
 
     Start the Flutter development server, targeting the Chrome browser: