Merge pull request #10 from flutter-news-app-full-source-code/reactor_docs_for_smoother_experience

fulleni · web-flow · commit 4c9b030f74ae · 2025-07-27T19:32:27.000+01:00
Reactor docs for smoother experience
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -17,29 +17,27 @@ export default defineConfig({
 				},
 			],
 			sidebar: [
-				{ label: 'Core Philosophy', link: '/core-philosophy' },
-				{ label: 'Local Setup', link: '/local-setup' },
-				{ label: 'Deployment', link: '/deployment' },
 				{
-					label: 'Architecture & Customization',
-					collapsed: true,
+					label: 'Getting Started',
 					items: [
+						{ label: 'Overview', link: '/getting-started/' },
+						{ label: 'Core Philosophy', link: '/getting-started/core-philosophy' },
+						{ label: 'Toolkit Architecture', link: '/getting-started/toolkit-architecture' },
+						{ label: 'Local Setup', link: '/getting-started/local-setup' },
+						{ label: 'Deployment', link: '/getting-started/deployment' },
+					],
+				},
+				{
+					label: 'Customization Guides',
+					items: [
+						{ label: 'Overview', link: '/customization/' },
 						{
-							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: 'Hosting Packages for Customization',
+							link: '/customization/hosting-packages-for-customization',
 						},
 						{
 							label: 'Guide: Customizing the UI Theme',
-							link: '/architecture/guide-customizing-the-ui',
+							link: '/customization/guide-customizing-the-ui',
 						},
 					],
 				},
@@ -81,7 +79,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' },
+								{ label: 'Error Handling', link: '/api-server/architecture/error-handling' },
 							],
 						},
 						{
@@ -97,7 +95,7 @@ export default defineConfig({
 						{ label: 'Deployment', link: '/api-server/deployment' },
 					],
 				},
-								{
+				{
 					label: 'Web Dashboard',
 					collapsed: true,
 					items: [
@@ -117,7 +115,7 @@ export default defineConfig({
 							label: 'Architecture',
 							collapsed: true,
 							items: [
-								{ label: 'Overview', link: '/web-dashboard/architecture/index' },
+								{ 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' },
 							],
diff --git a/src/content/docs/api-server/architecture/index.mdx b/src/content/docs/api-server/architecture/index.mdx
@@ -6,14 +6,3 @@ description: Dive deeper into the architectural patterns and advanced concepts o
 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.
-
-<CardGrid>
-  <Card title="Dependency Injection" icon="tree-structure">
-    Learn how the server manages and provides dependencies throughout the application.
-    [Read more &rarr;](/docs/api-server/advanced/dependency-injection)
-  </Card>
-  <Card title="Middleware" icon="layers">
-    Understand how middleware is used for cross-cutting concerns like authentication and logging.
-    [Read more &rarr;](/docs/api-server/advanced/middleware)
-  </Card>
-</CardGrid>
diff --git a/src/content/docs/api-server/features/index.mdx b/src/content/docs/api-server/features/index.mdx
@@ -24,8 +24,4 @@ The API server is packed with features designed for a modern, scalable news appl
     Explore the granular permission system that secures the API.
     [Read more &rarr;](/docs/api-server/features/rbac)
   </Card>
-  <Card title="Remote Configuration" icon="settings">
-    Learn how you can dynamically control app behavior from the server.
-    [Read more &rarr;](/docs/api-server/features/remote-config)
-  </Card>
 </CardGrid>
diff --git a/src/content/docs/api-server/guides/index.mdx b/src/content/docs/api-server/guides/index.mdx
@@ -24,8 +24,4 @@ This section provides practical, step-by-step guides for specific configuration
     See how to swap out the default email service with your own implementation.
     [Read more &rarr;](/docs/api-server/guides/implement-alternative-email-client/)
   </Card>
-  <Card title="Understand Database Seeding" icon="seed">
-    Learn how the server automatically populates the database with initial data.
-    [Read more &rarr;](/docs/api-server/guides/understand-database-seeding/)
-  </Card>
 </CardGrid>
diff --git a/src/content/docs/api-server/local-setup.mdx b/src/content/docs/api-server/local-setup.mdx
@@ -61,5 +61,5 @@ This guide will walk you through setting up the API server in a local developmen
 
     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.
 
-    For more details on how this works, see the [Understand Database Seeding](/docs/api-server/guides/understand-database-seeding) guide.
+    For more details on how this works, see the [Understand Database Seeding](/docs/api-server/architecture/data-seeding-and-fixtures) guide.
 </Steps>
diff --git a/src/content/docs/architecture/index.mdx b/src/content/docs/architecture/index.mdx
diff --git a/src/content/docs/customization/guide-customizing-the-ui.mdx b/src/content/docs/customization/guide-customizing-the-ui.mdx
@@ -1,23 +1,23 @@
 ---
 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.
+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. This process is the key to unlocking the full customization potential of the toolkit.
+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 take ownership of the `ui_kit` package, modify its theme file, and then instruct both of our Flutter applications to use our modified version.
+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.
 
 <Steps>
-1.  **Take Ownership of the `ui_kit` Package**
+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 [**Taking Ownership of Packages**](/docs/architecture/02-taking-ownership-of-packages/) guide from start to finish, but for the `ui_kit` 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.
@@ -30,7 +30,7 @@ Our goal is to change the default blue accent color of the application to a new
     -   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"
+    ```dart title="ui_kit/lib/src/theme/app_theme.dart"
     const FlexSubThemesData _commonSubThemesData = FlexSubThemesData(
       // ...
       // Change the app bar background color
@@ -90,4 +90,4 @@ Our goal is to change the default blue accent color of the application to a new
 
 ### 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.
+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
@@ -1,20 +1,20 @@
 ---
-title: Taking Ownership of Packages
-description: A step-by-step guide to cloning, hosting, and managing the shared packages for customization.
+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 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.
+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, one-time process of moving a shared package from the original public repository into your own private repository.
+This guide will walk you through the essential process of creating a private copy of a shared package from the original public 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
+### Why You Must Host a Private Copy
 
--   **To Enable Customization:** You cannot push changes to the original public repositories. To modify a package, you need your own version that you control.
+-   **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.
 
@@ -69,6 +69,6 @@ Let's walk through the process using the `core` package as an example. You will
 
 </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.
+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/architecture/03-guide-customizing-the-ui/), will walk you through this process in a practical, hands-on example.
+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
@@ -0,0 +1,18 @@
+---
+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.
+
+<CardGrid>
+	<Card title="Hosting Packages for Customization" icon="key">
+		This is the most critical guide. Learn how to create your own private version of a shared package to enable modification.
+		[Read more &rarr;](/docs/customization/hosting-packages-for-customization/)
+	</Card>
+	<Card title="Guide: Customizing the UI Theme" icon="palette">
+		Put theory into practice with a hands-on tutorial for customizing the UI theme by modifying the `ui_kit` package.
+		[Read more &rarr;](/docs/customization/guide-customizing-the-ui/)
+	</Card>
+</CardGrid>
diff --git a/src/content/docs/getting-started/core-philosophy.mdx b/src/content/docs/getting-started/core-philosophy.mdx
diff --git a/src/content/docs/getting-started/deployment.mdx b/src/content/docs/getting-started/deployment.mdx
diff --git a/src/content/docs/getting-started/index.mdx b/src/content/docs/getting-started/index.mdx
@@ -0,0 +1,32 @@
+---
+title: 'Getting Started'
+description: A step-by-step guide to evaluating, running, and customizing the Flutter News App Toolkit.
+---
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+Welcome to the Flutter News App Toolkit! This section provides a recommended path for all new users to ensure a smooth and successful experience.
+
+Whether you are evaluating the toolkit under the free trial license or are ready to build your production application, we suggest following these guides in the order they are presented.
+
+<CardGrid>
+	<Card title="1. Understand the Core Philosophy" icon="open-book">
+		Begin by learning about the production-ready principles that guided the toolkit's construction. This will help you understand the value and quality of the architecture.
+		[Read the Core Philosophy &rarr;](/docs/getting-started/core-philosophy/)
+	</Card>
+	<Card title="2. Understand the Toolkit Architecture" icon="file-tree">
+		Next, get a high-level overview of the multi-repository structure. Understanding how the applications and shared packages work together is essential for effective customization.
+		[Learn about the Architecture &rarr;](/docs/getting-started/toolkit-architecture/)
+	</Card>
+    <Card title="3. Run the Toolkit Locally" icon="laptop">
+		Follow our comprehensive setup guides to get the API Server, Web Dashboard, and Mobile Client running on your local machine.
+		[Go to Local Setup &rarr;](/docs/getting-started/local-setup/)
+	</Card>
+    <Card title="4. Learn to Customize" icon="puzzle">
+        Once you have the toolkit running, you'll want to learn how to modify it. This section covers the critical workflow for hosting your own versions of the shared packages.
+		[View Customization Guides &rarr;](/docs/customization/)
+	</Card>
+    <Card title="5. Deploy to Production" icon="rocket">
+        When you're ready to go live, these guides will walk you through deploying each component of the toolkit to a production environment.
+		[View Deployment Guides &rarr;](/docs/getting-started/deployment/)
+	</Card>
+</CardGrid>
diff --git a/src/content/docs/getting-started/local-setup.mdx b/src/content/docs/getting-started/local-setup.mdx
diff --git a/src/content/docs/getting-started/toolkit-architecture.mdx b/src/content/docs/getting-started/toolkit-architecture.mdx
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -7,8 +7,8 @@ hero:
   image:
     file: ../../assets/flutter-news-app-full-source-code-logo.png
   actions:
-    - text: 'Get Started: Local Setup'
-      link: /docs/local-setup/
+    - text: 'Get Started'
+      link: /docs/getting-started/
       icon: right-arrow
     - text: 'View Live Demos'
       link: '#toolkit-components'
@@ -116,7 +116,7 @@ This toolkit is source-available, allowing you to explore the code and ensure it
 		machine. The PolyForm Free Trial license allows for a full evaluation of the project's
 		quality and features.
 		<div style={{ marginTop: '1.5rem' }}>
-			<LinkButton href="/docs/local-setup/">Begin Local Setup</LinkButton>
+			<LinkButton href="/docs/getting-started/">Begin Setup</LinkButton>
 		</div>
 	</Card>
 	<Card title="Purchase a Lifetime License" icon="rocket">
diff --git a/src/content/docs/mobile-client/architecture/error-handling.mdx b/src/content/docs/mobile-client/architecture/error-handling.mdx
@@ -16,7 +16,7 @@ All exceptions that represent business logic or data fetching errors are subtype
 -   `OperationFailedException`: A general-purpose exception for other server-side or unexpected failures.
 
 <Aside>
-You can find the full set of standardized exceptions in the `packages/core/lib/src/exceptions/` directory.
+The full set of standardized exceptions is defined in the `core` shared package. After you have cloned the `core` repository locally, you can find them in its `lib/src/exceptions/` directory.
 </Aside>
 
 ### The Flow of an Exception
diff --git a/src/content/docs/mobile-client/guides/styling-and-theming.mdx b/src/content/docs/mobile-client/guides/styling-and-theming.mdx
@@ -11,7 +11,7 @@ Because this is a cross-application concern, the primary, hands-on guide for mak
 <Aside type="tip" title="Start Here for Customization">
 To learn how to properly customize the UI, please follow our comprehensive, step-by-step tutorial:
 
-[**Guide: Customizing the UI Theme &rarr;**](/docs/architecture/03-guide-customizing-the-ui/)
+[**Guide: Customizing the UI Theme &rarr;**](/docs/customization/)
 </Aside>
 
 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/mobile-client/local-setup.mdx b/src/content/docs/mobile-client/local-setup.mdx
@@ -15,11 +15,11 @@ This guide will walk you through setting up and running the Flutter News App Mob
 
 2.  **Clone the Repository**
 
-    Open your terminal, navigate to your desired workspace directory, and clone the mobile client repository:
+    Open your terminal and clone the mobile client repository:
 
     ```bash
     git clone https://github.com/flutter-news-app-full-source-code/flutter-news-app-mobile-client-full-source-code.git
-    cd apps/flutter-news-app-mobile-client-full-source-code
+    cd flutter-news-app-mobile-client-full-source-code
     ```
 
 3.  **Install Dependencies**
diff --git a/src/content/docs/web-dashboard/guides/styling-and-theming.mdx b/src/content/docs/web-dashboard/guides/styling-and-theming.mdx
@@ -11,7 +11,7 @@ Because this is a cross-application concern, the primary, hands-on guide for mak
 <Aside type="tip" title="Start Here for Customization">
 To learn how to properly customize the UI, please follow our comprehensive, step-by-step tutorial:
 
-[**Guide: Customizing the UI Theme &rarr;**](/docs/architecture/03-guide-customizing-the-ui/)
+[**Guide: Customizing the UI Theme &rarr;**](/docs/customization/)
 </Aside>
 
 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/local-setup.mdx b/src/content/docs/web-dashboard/local-setup.mdx
@@ -16,7 +16,7 @@ This guide will walk you through setting up and running the Flutter News App Web
 
 2.  **Clone the Repository**
 
-    Open your terminal, navigate to your desired workspace directory, and clone the web dashboard repository:
+    Open your terminal and clone the web dashboard repository:
 
     ```bash
     git clone https://github.com/flutter-news-app-full-source-code/flutter-news-app-web-dashboard-full-source-code.git
