Merge pull request #9 from flutter-news-app-full-source-code/packages_docs

Packages docs

Author: fulleni

astro.config.mjs

@@ -20,6 +20,29 @@ export default defineConfig({
 				{ label: 'Core Philosophy', link: '/core-philosophy' },
 				{ label: 'Local Setup', link: '/local-setup' },
 				{ label: 'Deployment', link: '/deployment' },
+				{
+					label: 'Architecture & Customization',
+					collapsed: true,
+					items: [
+						{
+							label: 'Overview',
+							link: '/architecture/index',
+						},
+
+						{
+							label: 'Understanding the Toolkit Architecture',
+							link: '/architecture/toolkit-architecture',
+						},
+						{
+							label: 'Taking Ownership of Packages',
+							link: '/architecture/taking-ownership-of-packages',
+						},
+						{
+							label: 'Guide: Customizing the UI Theme',
+							link: '/architecture/guide-customizing-the-ui',
+						},
+					],
+				},
 				{
 					label: 'API Server',
 					collapsed: true,
@@ -36,7 +59,6 @@ export default defineConfig({
 								{ 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: 'Error Handling', link: '/api-server/features/error-handling' },
 							],
 						},
 						{
@@ -59,6 +81,7 @@ export default defineConfig({
 								{ label: 'Middleware', link: '/api-server/architecture/middleware' },
 								{ label: 'Data Seeding & Fixtures', link: '/api-server/architecture/data-seeding-and-fixtures' },
 								{ label: 'Generic Data Endpoint', link: '/api-server/architecture/generic-data-endpoint' },
+								{ label: 'Error Handling', link: '/api-server/features/error-handling' },
 							],
 						},
 						{
@@ -103,7 +126,7 @@ export default defineConfig({
 							label: 'Guides',
 							collapsed: true,
 							items: [
-								{ label: 'Theming & Customization', link: '/web-dashboard/guides/theming-and-customization' },
+								{ label: 'Styling & Theming', link: '/web-dashboard/guides/styling-and-theming' },
 								{ label: 'Localization', link: '/web-dashboard/guides/localization' },
 							],
 						},

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

@@ -0,0 +1,93 @@
+---
+title: 'Guide: Customizing the UI Theme'
+description: A practical, step-by-step guide to customizing the UI theme by taking ownership 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. This process is the key to unlocking the full customization potential of the toolkit.
+
+### 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 take ownership of the `ui_kit` package, modify its theme file, and then instruct both of our Flutter applications to use our modified version.
+
+<Steps>
+1.  **Take Ownership 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 [**Taking Ownership of Packages**](/docs/architecture/02-taking-ownership-of-packages/) 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="packages/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.
+
+</Steps>
+
+### Conclusion
+
+You have successfully completed the core customization workflow. You now have a privately owned 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.

src/content/docs/architecture/guide-customizing-the-ui.mdx

@@ -0,0 +1,24 @@
+---
+title: 'Architecture & Customization'
+description: Learn how the toolkit is structured and how to take full ownership of the shared packages to customize your applications.
+---
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+Welcome to the Architecture & Customization section. This is the most important part of the documentation for developers who want to go beyond the default setup and truly make the toolkit their own.
+
+Here, you will learn about the multi-repository philosophy that underpins the toolkit and, most importantly, follow a step-by-step, practical guide to customizing the shared UI package and seeing your changes reflected across both the mobile and web applications.
+
+<CardGrid>
+	<Card title="1. Understand the Toolkit Architecture" icon="file-tree">
+		Start here to learn about the multi-repository structure and why it's designed this way.
+		[Read more &rarr;](/docs/architecture/01-toolkit-architecture/)
+	</Card>
+	<Card title="2. Take Ownership of Packages" icon="key">
+		Follow this critical guide to learn how to host the shared packages in your own private repositories.
+		[Read more &rarr;](/docs/architecture/02-taking-ownership-of-packages/)
+	</Card>
+	<Card title="3. Practical Guide: Customize the UI" icon="palette">
+		Put theory into practice with a hands-on tutorial for customizing the UI theme.
+		[Read more &rarr;](/docs/architecture/03-guide-customizing-the-ui/)
+	</Card>
+</CardGrid>

src/content/docs/architecture/index.mdx

@@ -0,0 +1,74 @@
+---
+title: Taking Ownership of Packages
+description: A step-by-step guide to cloning, hosting, and managing the shared packages for customization.
+---
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+To unlock the full power of the Flutter News App Toolkit and make it truly your own, you must take ownership 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, one-time process of moving a shared package from the original public repository into your own private repository.
+
+<Aside type="caution" title="Critical Step">
+This is the most important guide for customizing the toolkit. You must follow this process for **any shared package** you intend to modify.
+</Aside>
+
+### Why You Must Host the Packages Yourself
+
+-   **To Enable Customization:** 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`.
+
+<Steps>
+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
+    ```
+
+</Steps>
+
+**Congratulations!** You have now successfully taken ownership of the `core` package. It is now hosted in your private repository, and you are free to make any modifications you need.
+
+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/architecture/03-guide-customizing-the-ui/), will walk you through this process in a practical, hands-on example.

src/content/docs/architecture/taking-ownership-of-packages.mdx

@@ -0,0 +1,59 @@
+---
+title: Understanding the Toolkit Architecture
+description: An overview of the multi-repository architecture and how the apps and packages work together.
+---
+import { Card, CardGrid, Aside } from '@astrojs/starlight/components';
+
+Welcome to the architectural overview of the Flutter News App Toolkit. Understanding the structure of the toolkit is the first and most important step to customizing it effectively and making it your own.
+
+This toolkit is not a single, monolithic application. Instead, it is a collection of independent projects—three applications and a suite of shared packages—that work together. This is a deliberate and professional architectural choice that provides significant long-term benefits.
+
+### The Multi-Repository Philosophy
+
+The toolkit is divided into two main categories of repositories:
+
+<CardGrid>
+	<Card title="Applications" icon="laptop">
+		These are the user-facing projects that you will build and deploy. Each one is a standalone application in its own repository.
+        - **Mobile Client:** The Flutter app for iOS and Android.
+        - **Web Dashboard:** The Flutter web app for administration.
+        - **API Server:** The Dart Frog backend.
+	</Card>
+	<Card title="Shared Packages" icon="puzzle">
+		These are Dart packages that contain shared code, logic, and UI components. They are consumed by the applications as dependencies.
+        - **`core`**: Contains all shared data models and exceptions.
+        - **`data_repository`**: Handles the business logic for data fetching.
+        - **`ui_kit`**: Provides shared widgets, themes, and constants.
+        - ...and many others.
+	</Card>
+</CardGrid>
+
+### Why Is It Structured This Way?
+
+This decoupled, multi-repository approach is a best practice for building large, maintainable systems.
+
+-   **Code Reusability:** The `core` package ensures that the Mobile Client and the API Server are always using the exact same data models. The `ui_kit` ensures both Flutter apps have a consistent look and feel. This is the essence of **DRY (Don't Repeat Yourself)**.
+-   **Separation of Concerns:** Each piece of the toolkit has a single, clear responsibility. The `auth_repository` only handles authentication logic. The `http_client` only handles making network requests. This makes the code easier to understand, test, and debug.
+-   **Maintainability:** When you need to change the theme of your apps, you only need to edit the `ui_kit` package. When you need to add a new field to a data model, you only edit the `core` package. The changes then propagate to the consuming applications when you update the dependency.
+
+### How It All Connects: `pubspec.yaml`
+
+The link between the applications and the shared packages is the `pubspec.yaml` file in each application. When you first get the code, these files point to the original public GitHub repositories for each package.
+
+```yaml title="Example from an app's pubspec.yaml"
+dependencies:
+  # This app depends on the `core` package...
+  core:
+    # ...and it fetches it from this Git repository.
+    git:
+      url: https://github.com/flutter-news-app-full-source-code/core.git
+  
+  # It also depends on the `ui_kit` package.
+  ui_kit:
+    git:
+      url: https://github.com/flutter-news-app-full-source-code/ui-kit.git
+```
+
+<Aside type="tip">
+To truly customize the toolkit, you will need to host these packages in your own private repositories and update this `pubspec.yaml` file to point to your versions. The next guide will walk you through this essential process.
+</Aside>

src/content/docs/architecture/toolkit-architecture.mdx

@@ -3,10 +3,14 @@ title: 'Deployment: From Local to Live'
 description: A collection of guides to help you deploy the API server, mobile app, and web dashboard to production environments.
 ---
 
-import { Steps } from '@astrojs/starlight/components';
+import { Steps, Aside } from '@astrojs/starlight/components';
 
 Once you have the toolkit running on your local machine, the next step is to go live. These guides provide clear, step-by-step instructions for preparing and deploying each component of the toolkit to a production environment.
 
+<Aside type="note" title="Before You Deploy">
+It is highly recommended that you first complete the guides in the [**Architecture & Customization**](/docs/architecture/) section. This will ensure you have taken ownership of the shared packages and made any desired branding or functional changes before releasing your applications.
+</Aside>
+
 <Steps>
 1.  **Deploy the API Server**
 

src/content/docs/deployment.mdx

@@ -28,3 +28,11 @@ We recommend following the guides in the order presented to ensure a smooth setu
 
     [Go to Mobile App Setup Guide →](/docs/mobile-client/local-setup/)
 </Steps>
+
+### Next Steps: Customize Your Toolkit
+
+Congratulations! You now have the entire toolkit running locally. This is the perfect time to explore the architecture and learn how to make it your own.
+
+The next logical step is to dive into our **Architecture & Customization** section, where you will learn how to take ownership of the shared packages and begin customizing your applications.
+
+[**Go to Architecture & Customization &rarr;**](/docs/architecture/)