From 5a81e55063fafb31f4b23496d6be9b6eb54cfa52 Mon Sep 17 00:00:00 2001 From: fulleni Date: Wed, 8 Oct 2025 08:46:06 +0100 Subject: [PATCH 1/4] docs: remove getting started documentation - Remove core philosophy, toolkit architecture, and other related documents - Delete files and content related to the removed documentation - Update file paths and imports accordingly --- .../docs/getting-started/core-philosophy.mdx | 48 --------------- src/content/docs/getting-started/index.mdx | 32 ---------- .../getting-started/toolkit-architecture.mdx | 59 ------------------- 3 files changed, 139 deletions(-) delete mode 100644 src/content/docs/getting-started/core-philosophy.mdx delete mode 100644 src/content/docs/getting-started/index.mdx delete mode 100644 src/content/docs/getting-started/toolkit-architecture.mdx diff --git a/src/content/docs/getting-started/core-philosophy.mdx b/src/content/docs/getting-started/core-philosophy.mdx deleted file mode 100644 index 6978ee5..0000000 --- a/src/content/docs/getting-started/core-philosophy.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -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. - - - -### 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. diff --git a/src/content/docs/getting-started/index.mdx b/src/content/docs/getting-started/index.mdx deleted file mode 100644 index f754fe9..0000000 --- a/src/content/docs/getting-started/index.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -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. - - - - 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 →](/docs/getting-started/core-philosophy/) - - - 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 →](/docs/getting-started/toolkit-architecture/) - - - Follow our comprehensive setup guides to get the API Server, Web Dashboard, and Mobile Client running on your local machine. - [Go to Local Setup →](/docs/getting-started/local-setup/) - - - 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 →](/docs/customization/) - - - 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 →](/docs/getting-started/deployment/) - - diff --git a/src/content/docs/getting-started/toolkit-architecture.mdx b/src/content/docs/getting-started/toolkit-architecture.mdx deleted file mode 100644 index b4c5e4e..0000000 --- a/src/content/docs/getting-started/toolkit-architecture.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -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: - - - - 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. - - - 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. - - - -### 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 -``` - - From 4c42666627511f3d4863462df5af9348ea22092d Mon Sep 17 00:00:00 2001 From: fulleni Date: Wed, 8 Oct 2025 08:46:14 +0100 Subject: [PATCH 2/4] docs(getting-started): remove deployment aside note - Deleted the Aside component with the note about completing Customization guides before deployment - This change simplifies the deployment page content and removes a redundant instruction --- src/content/docs/getting-started/deployment.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/getting-started/deployment.mdx b/src/content/docs/getting-started/deployment.mdx index d07343c..02d5d1e 100644 --- a/src/content/docs/getting-started/deployment.mdx +++ b/src/content/docs/getting-started/deployment.mdx @@ -7,10 +7,6 @@ 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. - - 1. **Deploy the API Server** From a69b8135673a23cb8944c86e428544d34be5cf9f Mon Sep 17 00:00:00 2001 From: fulleni Date: Wed, 8 Oct 2025 08:46:25 +0100 Subject: [PATCH 3/4] docs: remove redundant getting started links - Removed 'Overview', 'Core Philosophy', and 'Toolkit Architecture' links from the sidebar - These pages have been duplicated in the sidebar since the /guide/ rewrite --- astro.config.mjs | 3 --- 1 file changed, 3 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 65f4c26..3b9e655 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -20,9 +20,6 @@ export default defineConfig({ { 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' }, ], From 48b3968981b18e494a16be8cd8f36820523e420e Mon Sep 17 00:00:00 2001 From: fulleni Date: Wed, 8 Oct 2025 08:47:57 +0100 Subject: [PATCH 4/4] docs: remove redundant cards from mobile client homepage - Deleted the 'Features', 'Architecture', and 'Developer Guides' cards from the mobile client homepage. - These sections are already accessible via the sidebar, making the cards redundant. --- src/content/docs/mobile-client/index.mdx | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/content/docs/mobile-client/index.mdx b/src/content/docs/mobile-client/index.mdx index 40d0d19..fa31e1f 100644 --- a/src/content/docs/mobile-client/index.mdx +++ b/src/content/docs/mobile-client/index.mdx @@ -16,16 +16,4 @@ The Mobile Client is a feature-rich, cross-platform mobile app built with Flutte Learn how to build and deploy the mobile app to the app stores. [Read more →](/docs/mobile-client/deployment/) - - Explore the key features, from the dynamic feed to user personalization. - [Read more →](/docs/mobile-client/features/) - - - Understand the architecture, state management, and navigation patterns. - [Read more →](/docs/mobile-client/architecture/) - - - Practical guides for developers on theming, customization, and localization. - [Read more →](/docs/mobile-client/guides/) -