Merge pull request #8 from flutter-news-app-full-source-code/final_polish

Final polish

Author: fulleni

astro.config.mjs

@@ -17,15 +17,9 @@ export default defineConfig({
 				},
 			],
 			sidebar: [
-				{
-					label: 'Start Here',
-					items: [
-						{ label: 'Introduction', link: '/start-here/introduction' },
-						{ label: 'Local Setup', link: '/start-here/local-setup' },
-						// { label: 'Core Philosophy', link: '/start-here/core-philosophy' },
-						{ label: 'Deployment Guides', link: '/start-here/deployment-guides' },
-					],
-				},
+				{ label: 'Core Philosophy', link: 'core-philosophy' },
+				{ label: 'Local Setup', link: 'local-setup' },
+				{ label: 'Deployment', link: 'deployment' },
 				{
 					label: 'API Server',
 					collapsed: true,
@@ -100,7 +94,7 @@ export default defineConfig({
 							label: 'Architecture',
 							collapsed: true,
 							items: [
-								{ label: 'Overview', link: '/web-dashboard/architecture/overview' },
+								{ label: 'Overview', link: '/web-dashboard/architecture/index' },
 								{ label: 'State Management (BLoC)', link: '/web-dashboard/architecture/state-management' },
 								{ label: 'Routing (go_router)', link: '/web-dashboard/architecture/routing' },
 							],

src/content/docs/api-server/deployment.mdx

@@ -1,44 +1,38 @@
 ---
-title: Deployment Guide
-description: Learn how to deploy the API server to a production environment.
+title: 'Deployment: API Server'
+description: A guide to building and deploying the Dart Frog API server to a production environment.
 ---
 
 import { Steps, Aside } from '@astrojs/starlight/components';
 
-This guide outlines the strategy for deploying the API server to a production environment. The recommended method is to use Docker, which creates a portable and consistent container for your application.
+This guide outlines the process for deploying the API server to a production environment. The server is built with Dart Frog and packaged as a Docker container, making it portable and easy to deploy to any hosting provider that supports Docker.
 
 <Aside>
-The world of cloud hosting and deployment tools evolves rapidly. Instead of providing specific commands that could become outdated, this guide focuses on the essential steps and links to the official documentation for the relevant services. This ensures you always have access to the most current and accurate instructions.
+To ensure you have the most reliable and up-to-date instructions, this guide focuses on the project-specific configuration you need to complete. For the deployment itself, we will refer you to the excellent official documentation from the Dart Frog team, which is the definitive resource.
 </Aside>
 
-<Steps>
-1.  **Configure Production Environment Variables**
+### Pre-Deployment Configuration
 
-    Your first step is to prepare the production configuration for the server. Unlike local development which uses a `.env` file, in production you will use your hosting provider's interface to set environment variables securely.
+Before you can deploy, you must complete two essential configuration steps.
 
-    For a detailed explanation of each required variable, please see the [Configure Environment Variables](/docs/api-server/guides/configure-environment-variables) guide.
-
-2.  **Choose a Deployment Strategy**
+<Steps>
+1.  **Configure Production Environment Variables**
 
-    The API server repository includes a `Dockerfile`, which allows for two main deployment strategies:
+    In your production environment, you will not use a `.env` file. Instead, you must configure the environment variables directly in your chosen hosting provider's interface. This is a critical step for security and proper configuration.
 
-    -   **Deploying a Pre-built Image:** You build the Docker image on your local machine or in a CI/CD pipeline, push it to a container registry (like Docker Hub, Google Container Registry, or Amazon ECR), and then your hosting provider pulls the image from the registry.
-    -   **Deploying from Source:** You connect your Git repository directly to the hosting provider, and it uses the `Dockerfile` to build and deploy the image for you.
+    For a detailed explanation of each required variable, please see the [**Configure Environment Variables Guide**](/docs/api-server/guides/configure-environment-variables).
 
-3.  **Deploy to a Hosting Provider**
+2.  **Configure CORS**
 
-    Choose a hosting provider that supports Docker container deployments. Popular and well-documented options include:
-    -   [Google Cloud Run](https://cloud.google.com/run/docs/deploying)
-    -   [Amazon Elastic Container Service (ECS)](https://aws.amazon.com/ecs/)
-    -   [DigitalOcean App Platform](https://www.digitalocean.com/docs/app-platform/)
-    -   [Render](https://render.com/docs/docker)
+    For the Web Dashboard to communicate with your API in production, you must correctly configure Cross-Origin Resource Sharing (CORS) by setting the `CORS_ALLOWED_ORIGIN` environment variable.
 
-    Follow the official documentation from your chosen provider to deploy your container. During the setup process, you will be prompted to configure the environment variables from Step 1.
+    For instructions, see the [**Configure CORS Guide**](/docs/api-server/guides/configure-cors).
+</Steps>
 
-4.  **Configure CORS**
+### Deployment with Dart Frog
 
-    For your web-based dashboard to communicate with the API in production, you must correctly configure Cross-Origin Resource Sharing (CORS).
+Once your configuration is ready, you can proceed with the deployment. The Dart Frog documentation provides comprehensive guides for various hosting providers and deployment strategies (e.g., using Docker, deploying to Google Cloud Run, etc.).
 
-    For instructions, see the [Configure CORS](/docs/api-server/guides/configure-cors) guide.
+Following the official documentation is the recommended and most reliable path to a successful deployment.
 
-</Steps>
+**[Official Dart Frog Deployment Guides](https://dartfrog.vgv.dev/docs/category/deploy)**

src/content/docs/api-server/guides/implement-alternative-email-client.mdx

@@ -13,10 +13,10 @@ This guide demonstrates the value of this architecture by walking you through th
 
 The core of this flexibility is the `EmailClient` abstract class, defined in the `email_client` package. Any email service you wish to use must have a corresponding class that implements this interface.
 
-The contract is simple:
+The contract, defined in the `email_client` package, is simple:
 
 ```dart
-// path: packages/email_client/lib/src/email_client.dart
+// lib/src/email_client.dart
 abstract class EmailClient {
   const EmailClient();
 
@@ -34,7 +34,7 @@ abstract class EmailClient {
 Let's create a simple "logging" email client that doesn't actually send emails but instead prints the details to the console. This is useful for local development or testing.
 
 1.  **Create the Implementation File:**
-    Create a new file, for example, `packages/email_logging/lib/src/email_logging.dart`.
+    You can create a new implementation anywhere, but for this example, let's assume you create a new local file for testing purposes.
 
 2.  **Implement the `EmailClient`:**
 
@@ -71,7 +71,7 @@ Let's create a simple "logging" email client that doesn't actually send emails b
 
 Swapping the implementation is the easiest part. You only need to change a single part of the dependency injection setup.
 
-Open the dependency configuration file: `apps/flutter-news-app-api-server-full-source-code/lib/src/config/app_dependencies.dart`.
+Open the dependency configuration file within the API server project: `lib/src/config/app_dependencies.dart`.
 
 <Tabs>
 <TabItem label="Before (Default)">

src/content/docs/api-server/index.mdx

@@ -1,6 +1,6 @@
 ---
-title: API Server
-description: An overview of the high-performance Dart Frog backend that powers the Flutter News App ecosystem.
+title: 'API Server: Introduction'
+description: An overview of the high-performance Dart Frog backend that powers the Flutter News App toolkit.
 ---
 
 import { Card, CardGrid } from '@astrojs/starlight/components';
@@ -10,24 +10,28 @@ The API Server is the core backend component of the Flutter News App Toolkit. Bu
 It is designed to work seamlessly with the [Mobile Client](/docs/mobile-client/) and the [Web Dashboard](/docs/web-dashboard/).
 
 <CardGrid>
-  <Card title="Getting Started" icon="rocket">
+  <Card title="Local Setup" icon="rocket">
     Follow the local setup guide to get the server running on your machine.
-    [Read more &rarr;](/docs/api-server/getting-started/)
+    [Read more &rarr;](/docs/api-server/local-setup/)
   </Card>
   <Card title="Deployment" icon="cloud">
     Learn how to deploy the API server to a production environment.
     [Read more &rarr;](/docs/api-server/deployment/)
   </Card>
   <Card title="Features" icon="puzzle">
-    Explore the key features and architecture of the API server.
-    [Read more &rarr;](/docs/api-server/features/authentication/)
+    Explore the key features of the API server, from authentication to data management.
+    [Read more &rarr;](/docs/api-server/features/)
+  </Card>
+  <Card title="Architecture" icon="tree-structure">
+    Dive into the architectural patterns that make the server robust and maintainable.
+    [Read more &rarr;](/docs/api-server/architecture/)
   </Card>
   <Card title="API Reference" icon="open-book">
     A complete reference for all API endpoints and data models.
     [Read more &rarr;](/docs/api-server/reference/)
   </Card>
   <Card title="How-To Guides" icon="document">
     Practical guides for specific configuration and setup tasks.
-    [Read more &rarr;](/docs/api-server/guides/configure-environment-variables/)
+    [Read more &rarr;](/docs/api-server/guides/)
   </Card>
 </CardGrid>

src/content/docs/core-philosophy.mdx

@@ -0,0 +1,48 @@
+---
+title: 'Core Philosophy: Built for Production'
+description: An overview of the architectural principles that ensure the toolkit is robust, maintainable, and scalable.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This toolkit was not just built to work; it was architected to last. Every component, from the backend API to the mobile client, is built on a foundation of production-ready principles. Understanding this philosophy is key to appreciating the long-term value and maintainability of the source code you've acquired.
+
+Our goal is to provide a codebase that is a pleasure to work with—one that you can confidently build upon, customize, and scale.
+
+### The "Make it Right" Principle
+
+Our guiding principle is to **default to production-ready patterns**, even when simpler alternatives exist. This prioritizes long-term code quality, testability, and maintainability over short-term implementation speed.
+
+Key aspects of this principle include:
+
+-   **Dependency Injection:** We consistently use dependency injection (DI) throughout the toolkit. Services, repositories, and clients are injected rather than instantiated directly. This decouples our components, making them easy to test in isolation and simple to swap out. For example, the default SendGrid email client can be replaced with another provider by changing a single line in the DI container.
+
+-   **Immutability:** All data models and state classes are immutable. This leads to more predictable state management, eliminates a whole class of potential bugs related to side effects, and makes debugging easier.
+
+-   **Testability by Design:** The entire system is structured to be easily testable. With clear boundaries between layers and the use of DI, you can write targeted unit tests for business logic without needing to run the entire application. We mandate a high test coverage standard across all packages.
+
+### A Clean, Layered Architecture
+
+The toolkit follows a classic layered architecture, ensuring a clear separation of concerns. This structure is applied consistently across all applications.
+
+1.  **Data Layer (Clients):** The lowest layer, responsible for all communication with external sources (like the database or third-party APIs). It handles the raw data fetching and maps external errors to a set of standardized exceptions.
+
+2.  **Repository Layer:** This layer abstracts the data sources. It provides a clean, consistent API for the business logic layer to consume, without needing to know *how* or *where* the data is stored.
+
+3.  **Business Logic Layer (BLoC / Services):** This layer contains the core application logic. In the Flutter apps, this is implemented using the **BLoC pattern**. In the backend, it's handled by **Services**. This layer orchestrates data from repositories and enforces business rules.
+
+4.  **Presentation Layer (UI / Routes):** The top layer, responsible for presenting data to the user and capturing their input. In the Flutter apps, this is the widget tree. In the API server, these are the route handlers. This layer is kept as "dumb" as possible, reacting to state changes from the business logic layer.
+
+<Aside>
+This clean separation means you can change the UI without touching business logic, or swap a database without affecting the UI. This is the key to a maintainable and scalable application.
+</Aside>
+
+### Standardized and Predictable Code
+
+-   **Shared `core` Package:** A central `core` package contains all shared data models, enumerations, and a standardized set of `Exception` classes. This ensures that the mobile client, web dashboard, and API server all speak the same language.
+
+-   **Consistent Error Handling:** All errors are mapped to the standardized exceptions from the `core` package at the data layer. This means BLoCs and services can handle errors in a predictable way, regardless of their origin.
+
+-   **Strict Data Modeling:** All data models follow strict rules: they are immutable, use `camelCase` for JSON serialization, and forbid optional properties to prevent null-related errors.
+
+By adhering to these principles, we've created a toolkit that is not only functional but also robust, testable, and ready for you to build your business on.

src/content/docs/start-here/deployment-guides.mdx renamed to src/content/docs/deployment.mdx

@@ -1,22 +1,22 @@
 ---
-title: 'Deployment Guides: From Local to Live'
+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';
 
-Once you have the ecosystem running locally, the next step is to deploy the components to production. These guides provide step-by-step instructions for preparing and deploying each part of the toolkit.
+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.
 
 <Steps>
 1.  **Deploy the API Server**
 
-    Learn how to configure and deploy the Dart Frog backend to a production server using Docker.
+    Learn how to configure and deploy the Dart Frog backend to a production server.
 
     [Go to API Deployment Guide &rarr;](/docs/api-server/deployment/)
 
 2.  **Deploy the Web Dashboard**
 
-    Follow these steps to build and deploy the Flutter web dashboard to a static hosting provider.
+    Follow the steps to build and deploy the Flutter web dashboard to your preferred hosting provider.
 
     [Go to Dashboard Deployment Guide &rarr;](/docs/web-dashboard/deployment/)
 

src/content/docs/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: 'Your Flutter News App - Ready to Launch'
+title: 'Your Full-Stack Flutter News App - Ready to Launch'
 description: A complete, production-ready toolkit for building a cross-platform news application.
 template: splash
 hero:
@@ -8,21 +8,23 @@ hero:
     file: ../../assets/flutter-news-app-full-source-code-logo.png
   actions:
     - text: 'Get Started: Local Setup'
-      link: /docs/getting-started/
+      link: /docs/local-setup/
       icon: right-arrow
     - text: 'View Live Demos'
-      link: '#ecosystem'
+      link: '#toolkit-components'
       icon: 'down-arrow'
       variant: minimal
 ---
 
 import { Card, CardGrid, LinkButton } from '@astrojs/starlight/components';
 
-<div id="ecosystem">
-	## A Complete, Production-Ready Ecosystem
-</div>
+## A Complete, Production-Ready Toolkit
+
+Welcome to the Flutter News App Full Source Code Toolkit. This is more than just an app template; it's a complete, three-part toolkit designed to work seamlessly together, giving you everything you need to launch, manage, and scale a modern news application from a solid, well-architected foundation.
 
-Welcome to the Flutter News App Full Source Code Toolkit. This is more than just an app template; it's a complete, three-part ecosystem designed to work seamlessly together, giving you everything you need to launch, manage, and scale a modern news application.
+<div id="toolkit-components">
+	### The Toolkit Components
+</div>
 
 <CardGrid>
 	<Card title="Mobile Client App" icon="phone">
@@ -46,7 +48,7 @@ Welcome to the Flutter News App Full Source Code Toolkit. This is more than just
 				href="https://github.com/flutter-news-app-full-source-code/flutter-news-app-mobile-client-full-source-code"
 				target="_blank"
 			>
-				Download
+				Browse on GitHub
 			</a>
 		</div>
 	</Card>
@@ -71,7 +73,7 @@ Welcome to the Flutter News App Full Source Code Toolkit. This is more than just
 				href="https://github.com/flutter-news-app-full-source-code/flutter-news-app-web-dashboard-full-source-code"
 				target="_blank"
 			>
-				Download
+				Browse on GitHub
 			</a>
 		</div>
 	</Card>
@@ -92,25 +94,33 @@ Welcome to the Flutter News App Full Source Code Toolkit. This is more than just
 				href="https://github.com/flutter-news-app-full-source-code/flutter-news-app-api-server-full-source-code"
 				target="_blank"
 			>
-				Download
+				Browse on GitHub
 			</a>
 		</div>
 	</Card>
 </div>
 
-## Choose Your Path
+## How the Toolkit Fits Together
+
+The **API Server** is the central brain. Both the **Mobile Client** and the **Web Dashboard** communicate with it to fetch data, authenticate users, and retrieve configuration. The **Web Dashboard** is used to populate the content that the **Mobile Client** displays.
+
+This separation of concerns makes the toolkit robust and flexible. You can manage your entire platform from the web and deliver updates to your mobile users instantly.
+
+## Get Started: Try, Evaluate, and Launch
+
+This toolkit is source-available, allowing you to explore the code and ensure it meets your standards before making a commitment.
 
 <CardGrid>
-	<Card title="Start Your 32-Day Trial" icon="laptop">
+	<Card title="Start Your Free Trial" icon="laptop">
 		Download the complete source code and run the entire system on your local
-		machine. The trial license allows for a full evaluation of the project's
-		quality and features for 32 days.
+		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/getting-started/">Begin Local Setup</LinkButton>
+			<LinkButton href="/docs/local-setup/">Begin Local Setup</LinkButton>
 		</div>
 	</Card>
 	<Card title="Purchase a Lifetime License" icon="rocket">
-		A one-time purchase grants you a lifetime commercial license to build,
+		Ready to go live? A one-time purchase grants you a lifetime commercial license to build,
 		customize, and deploy unlimited applications, complete with lifetime
 		updates.
 		<div style={{ marginTop: '1.5rem' }}>