diff --git a/astro.config.mjs b/astro.config.mjs index 2e36e41..a9f64dd 100644 --- a/astro.config.mjs +++ b/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' }, ], diff --git a/src/content/docs/api-server/deployment.mdx b/src/content/docs/api-server/deployment.mdx index f3b02bd..4e6e1a2 100644 --- a/src/content/docs/api-server/deployment.mdx +++ b/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. - -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** + +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). + -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. - +**[Official Dart Frog Deployment Guides](https://dartfrog.vgv.dev/docs/category/deploy)** diff --git a/src/content/docs/api-server/guides/implement-alternative-email-client.mdx b/src/content/docs/api-server/guides/implement-alternative-email-client.mdx index adff0d0..8d597b4 100644 --- a/src/content/docs/api-server/guides/implement-alternative-email-client.mdx +++ b/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`. diff --git a/src/content/docs/api-server/index.mdx b/src/content/docs/api-server/index.mdx index f16ab9d..4e59020 100644 --- a/src/content/docs/api-server/index.mdx +++ b/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,17 +10,21 @@ 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/). - + Follow the local setup guide to get the server running on your machine. - [Read more →](/docs/api-server/getting-started/) + [Read more →](/docs/api-server/local-setup/) Learn how to deploy the API server to a production environment. [Read more →](/docs/api-server/deployment/) - Explore the key features and architecture of the API server. - [Read more →](/docs/api-server/features/authentication/) + Explore the key features of the API server, from authentication to data management. + [Read more →](/docs/api-server/features/) + + + Dive into the architectural patterns that make the server robust and maintainable. + [Read more →](/docs/api-server/architecture/) A complete reference for all API endpoints and data models. @@ -28,6 +32,6 @@ It is designed to work seamlessly with the [Mobile Client](/docs/mobile-client/) Practical guides for specific configuration and setup tasks. - [Read more →](/docs/api-server/guides/configure-environment-variables/) + [Read more →](/docs/api-server/guides/) diff --git a/src/content/docs/core-philosophy.mdx b/src/content/docs/core-philosophy.mdx new file mode 100644 index 0000000..6978ee5 --- /dev/null +++ b/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. + + + +### 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/start-here/deployment-guides.mdx b/src/content/docs/deployment.mdx similarity index 64% rename from src/content/docs/start-here/deployment-guides.mdx rename to src/content/docs/deployment.mdx index ddf1d5d..cc9b8f4 100644 --- a/src/content/docs/start-here/deployment-guides.mdx +++ b/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. 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 →](/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 →](/docs/web-dashboard/deployment/) diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 10549f7..ddd5b57 100644 --- a/src/content/docs/index.mdx +++ b/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'; -
- ## A Complete, Production-Ready Ecosystem -
+## 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. +
+ ### The Toolkit Components +
@@ -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 @@ -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 @@ -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 -## 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. - + 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.
- Begin Local Setup + Begin Local Setup
- 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.
diff --git a/src/content/docs/local-setup.mdx b/src/content/docs/local-setup.mdx new file mode 100644 index 0000000..a2fe7ba --- /dev/null +++ b/src/content/docs/local-setup.mdx @@ -0,0 +1,30 @@ +--- +title: 'Getting Started: Local Setup' +description: A guide to setting up the complete Flutter News App toolkit on your local machine. +--- + +import { Steps } from '@astrojs/starlight/components'; + +Welcome to the local setup guide. Following these steps will get the complete toolkit—the API Server, Web Dashboard, and Mobile Client—running on your local machine for evaluation and development. + +We recommend following the guides in the order presented to ensure a smooth setup process. + + +1. **Set Up the API Server** + + Start by getting the backend running. The API server is the core of the toolkit, handling data and authentication for both clients. + + [Go to API Setup Guide →](/docs/api-server/local-setup/) + +2. **Set Up the Web Dashboard** + + Next, run the web-based administrative dashboard. You'll use this to manage content and see the system in action. + + [Go to Dashboard Setup Guide →](/docs/web-dashboard/local-setup/) + +3. **Set Up the Mobile Client** + + Finally, set up the Flutter mobile app for iOS and Android to explore the end-user experience. + + [Go to Mobile App Setup Guide →](/docs/mobile-client/local-setup/) + diff --git a/src/content/docs/mobile-client/deployment.mdx b/src/content/docs/mobile-client/deployment.mdx index 612236d..cc627c6 100644 --- a/src/content/docs/mobile-client/deployment.mdx +++ b/src/content/docs/mobile-client/deployment.mdx @@ -4,20 +4,18 @@ description: A guide to building and deploying the Flutter mobile app for Androi --- import { Steps, Aside } from '@astrojs/starlight/components'; -This guide provides a high-level overview of the tasks required to build and deploy the Flutter News App Mobile Client to the Google Play Store and Apple App Store. +This guide outlines the process for deploying the Flutter News App Mobile Client to the Google Play Store and Apple App Store. -For detailed, step-by-step instructions, this guide will link to the official Flutter and platform documentation. These are the definitive resources and are always kept up-to-date. + -### Prerequisites +### Pre-Deployment Configuration -Before you begin, you will need active developer accounts for the platforms you are targeting: -- **Google Play Console:** [developer.android.com/distribute](https://developer.android.com/distribute) -- **Apple Developer Program:** [developer.apple.com/programs](https://developer.apple.com/programs/) +Before you can build the app for production, you must configure it to connect to your live API server. -1. **Configure for Production** - - First, ensure the app is configured to connect to your live production API. +1. **Set the Production Environment** - Open the file `lib/main.dart`. - Locate the `appEnvironment` constant. @@ -28,32 +26,18 @@ Before you begin, you will need active developer accounts for the platforms you const appEnvironment = AppEnvironment.production; ``` - - -2. **Follow the Official Flutter Deployment Guides** - - The Flutter team provides comprehensive guides that cover every aspect of building and releasing your application. Please follow the official guide for each platform you intend to deploy to. +2. **Verify the API Base URL** - #### **Android (Google Play Store)** + - 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/). - The official guide covers essential steps including: - - Updating the Package ID (`applicationId`). - - Generating app icons. - - Creating an upload keystore and configuring app signing. - - Building the app bundle (`.aab`) for release. - - **[Official Guide: Build and release an Android app](https://docs.flutter.dev/deployment/android)** + - #### **iOS (Apple App Store)** +### Building and Releasing - The official guide covers essential steps including: - - Updating the Bundle Identifier and Display Name in Xcode. - - Generating the app icon set. - - Configuring app signing with your Apple Developer account. - - Building the release archive (`.ipa`) for upload. +Once your configuration is ready, you can proceed with building and releasing the application. The official Flutter documentation provides comprehensive, platform-specific guides that cover every required step, from generating app icons to configuring code signing and uploading to the stores. - **[Official Guide: Build and release an iOS app](https://docs.flutter.dev/deployment/ios)** +Following these official guides is the recommended and most reliable path to a successful release. - +- **[Official Guide: Build and release an Android app](https://docs.flutter.dev/deployment/android)** +- **[Official Guide: Build and release an iOS app](https://docs.flutter.dev/deployment/ios)** diff --git a/src/content/docs/mobile-client/features/index.mdx b/src/content/docs/mobile-client/features/index.mdx new file mode 100644 index 0000000..0c37eeb --- /dev/null +++ b/src/content/docs/mobile-client/features/index.mdx @@ -0,0 +1,39 @@ +--- +title: Features +description: Explore the key features of the Flutter News App Mobile Client. +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +The mobile client is packed with features designed for a modern, engaging news application. Explore the guides below to understand its core capabilities. + + + + Learn how the main news feed is managed, including filtering and dynamic content. + [Read more →](/docs/mobile-client/features/headlines-feed/) + + + Learn how the mobile client displays individual articles and similar content. + [Read more →](/docs/mobile-client/features/headline-details/) + + + Learn how the app displays detailed pages for topics and sources. + [Read more →](/docs/mobile-client/features/entity-details/) + + + Learn how the search feature allows users to find headlines, topics, and sources. + [Read more →](/docs/mobile-client/features/search/) + + + Learn how user authentication is handled in the mobile client. + [Read more →](/docs/mobile-client/features/authentication/) + + + Learn how users can manage their preferences, saved articles, and followed content. + [Read more →](/docs/mobile-client/features/account/) + + + Learn how users can customize the application's appearance, language, and feed display. + [Read more →](/docs/mobile-client/features/settings/) + + diff --git a/src/content/docs/mobile-client/guides/index.mdx b/src/content/docs/mobile-client/guides/index.mdx new file mode 100644 index 0000000..cb57cf9 --- /dev/null +++ b/src/content/docs/mobile-client/guides/index.mdx @@ -0,0 +1,19 @@ +--- +title: Developer Guides +description: Practical guides for developers on theming, customization, and localization for the mobile client. +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +This section provides practical, step-by-step guides for developers working on the mobile client. + + + + Learn how to customize the application's visual appearance. + [Read more →](/docs/mobile-client/guides/styling-and-theming/) + + + A guide to adding new languages and translations to the mobile client. + [Read more →](/docs/mobile-client/guides/localization/) + + diff --git a/src/content/docs/mobile-client/index.mdx b/src/content/docs/mobile-client/index.mdx index a536287..40d0d19 100644 --- a/src/content/docs/mobile-client/index.mdx +++ b/src/content/docs/mobile-client/index.mdx @@ -1,42 +1,31 @@ --- -title: Introduction -description: An overview of the Flutter News App Mobile Client. +title: 'Mobile Client: Introduction' +description: An overview of the Flutter News App Mobile Client for iOS and Android. --- import { Card, CardGrid } from '@astrojs/starlight/components'; -Welcome to the documentation for the Flutter News App Mobile Client, a key component of the Flutter News App Toolkit. This application is a feature-rich, cross-platform mobile app built with Flutter, designed to deliver a seamless and engaging news consumption experience to your users on both iOS and Android. - -## Core Technologies - -The mobile client is built on a modern, scalable, and maintainable tech stack, ensuring a high-quality foundation for your product. - -- **Framework**: [Flutter](https://flutter.dev/) for building beautiful, natively compiled applications for mobile from a single codebase. -- **State Management**: [Bloc](https://bloclibrary.dev/) for predictable and testable state management, separating business logic from the UI. -- **Routing**: [go_router](https://pub.dev/packages/go_router) for a declarative, URL-based navigation system that is robust and easy to manage. -- **Architecture**: Follows the layered architecture principles outlined in the Core Philosophy, ensuring a clean separation of concerns between the UI, business logic, and data layers. - -## Key Features - -The mobile client comes packed with features designed to provide a comprehensive user experience. +The Mobile Client is a feature-rich, cross-platform mobile app built with Flutter, designed to deliver a seamless and engaging news consumption experience to your users on both iOS and Android. It is the primary end-user-facing component of the toolkit. - - A customizable news feed that supports pagination, pull-to-refresh, and dynamic content injection for ads and user engagement prompts. + + Follow the local setup guide to get the mobile client running on your machine. + [Read more →](/docs/mobile-client/local-setup/) - - Users can search for headlines, topics, or sources, with results displayed in a clear and intuitive interface. + + Learn how to build and deploy the mobile app to the app stores. + [Read more →](/docs/mobile-client/deployment/) - - Authenticated users can personalize their experience by following topics and sources, and saving articles to read later. + + Explore the key features, from the dynamic feed to user personalization. + [Read more →](/docs/mobile-client/features/) - - A detailed settings module allows users to customize the app's appearance, theme, font size, language, and feed display preferences. + + 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/) - -## Getting Started - -To get the mobile client up and running on your local machine, head over to our setup guide. - -- **[Local Setup Guide](./mobile-client/local-setup)** diff --git a/src/content/docs/start-here/core-philosophy.mdx b/src/content/docs/start-here/core-philosophy.mdx deleted file mode 100644 index fff4e3b..0000000 --- a/src/content/docs/start-here/core-philosophy.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: 'Core Philosophy' -description: The architectural principles behind the API server. ---- - -This page will detail the core architectural philosophies of the project, such as Clean Code, SOLID principles, and the focus on maintainability and extensibility. diff --git a/src/content/docs/start-here/introduction.mdx b/src/content/docs/start-here/introduction.mdx deleted file mode 100644 index b5c25f4..0000000 --- a/src/content/docs/start-here/introduction.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: 'Introduction: A Complete Toolkit' -description: An overview of the Flutter News App Full Source Code toolkit, a production-ready ecosystem for launching a modern news platform. ---- - -import { Card, CardGrid, LinkButton } from '@astrojs/starlight/components'; - -## Welcome to the Toolkit - -Welcome to the Flutter News App Full Source Code Toolkit, a production-ready, three-part ecosystem designed for seamless integration. It provides everything you need to launch, manage, and scale a modern news application. - -Each component is built on a foundation of clean architecture, ensuring the system is maintainable, scalable, and a pleasure to work with. - -## The Ecosystem - -The toolkit is composed of three core pillars. Understanding the role of each is the first step to mastering the system. - - - - A feature-rich Flutter application for iOS and Android that delivers a - beautiful, intuitive news reading experience to your users. It is the primary - end-user-facing component. - - - A comprehensive Flutter web app for administrators and publishers to manage - content, configure app settings, and view key analytics. This is your - control center. - - - A high-performance backend built with Dart Frog, providing robust APIs for - authentication, data management, and remote configuration that serve both the - mobile and web clients. - - - -## How It 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 system robust and flexible. You can manage your entire platform from the web and deliver updates to your mobile users instantly. \ No newline at end of file diff --git a/src/content/docs/start-here/local-setup.mdx b/src/content/docs/start-here/local-setup.mdx deleted file mode 100644 index d37f73d..0000000 --- a/src/content/docs/start-here/local-setup.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Getting Started: Local Setup' -description: An overview of the local setup process for the entire Flutter News App ecosystem. ---- - -import { Steps } from '@astrojs/starlight/components'; - -Welcome to the local setup guide for the Flutter News App Toolkit. To get the full ecosystem running on your local machine, you will need to set up each of the three core components: the **API Server**, the **Web Dashboard**, and the **Mobile Client**. - -Follow the guides below in the recommended order to ensure a smooth setup process. - - -1. **Set Up the API Server** - - Start by getting the backend running. The API server handles data, authentication, and configuration for both the dashboard and the mobile app. - - [Go to API Setup Guide →](/docs/api-server/local-setup/) - -2. **Set Up the Web Dashboard** - - Next, run the web-based administrative dashboard. You'll use this to manage content and configure the application. - - [Go to Dashboard Setup Guide →](/docs/web-dashboard/local-setup/) - -3. **Set Up the Mobile Client** - - Finally, set up the Flutter mobile app for iOS and Android to see the end-user experience. - - [Go to Mobile App Setup Guide →](/docs/mobile-client/local-setup/) - diff --git a/src/content/docs/web-dashboard/architecture/index.mdx b/src/content/docs/web-dashboard/architecture/index.mdx new file mode 100644 index 0000000..ef13361 --- /dev/null +++ b/src/content/docs/web-dashboard/architecture/index.mdx @@ -0,0 +1,19 @@ +--- +title: Architecture +description: An overview of the architectural patterns and structure of the Flutter web dashboard. +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +The Flutter News App Web Dashboard is built upon a clean, scalable, and maintainable architecture that separates concerns into distinct layers. This approach, combined with the use of shared packages, ensures that the codebase is both robust and easy to extend. + + + + An explanation of how the BLoC pattern is used for state management. + [Read more →](/docs/web-dashboard/architecture/state-management/) + + + An explanation of how navigation and routing are handled using go_router. + [Read more →](/docs/web-dashboard/architecture/routing/) + + diff --git a/src/content/docs/web-dashboard/architecture/overview.mdx b/src/content/docs/web-dashboard/architecture/overview.mdx deleted file mode 100644 index d289697..0000000 --- a/src/content/docs/web-dashboard/architecture/overview.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Architecture Overview -description: An overview of the architectural patterns and structure of the Flutter web dashboard. ---- - -import { Aside } from '@astrojs/starlight/components'; - -The Flutter News App Web Dashboard is built upon a clean, scalable, and maintainable architecture that separates concerns into distinct layers. This approach, combined with the use of shared packages, ensures that the codebase is both robust and easy to extend. - -### Layered Architecture - -The dashboard follows a classic layered architecture, ensuring a clear separation of responsibilities: - -1. **Presentation Layer (UI):** This is the user-facing layer, built with Flutter widgets. It is responsible for displaying the UI and capturing user input. It is kept as "dumb" as possible, meaning it contains minimal logic and simply reflects the state provided by the Business Logic Layer. - -2. **Business Logic Layer (BLoC):** This layer contains the application's state management and business rules. We use the **BLoC (Business Logic Component)** pattern to manage the flow of information from user events to UI states. Feature-specific BLoCs (e.g., `ContentManagementBloc`, `DashboardBloc`) orchestrate data from the Repository Layer and emit states for the UI to consume. - -3. **Repository Layer:** This layer abstracts the origin of the data. It provides a clean, simple API for the Business Logic Layer to access data, without needing to know whether the data is coming from a remote API or a local in-memory source. This is a key part of our strategy for testability and environment flexibility. - -4. **Data Layer (Clients):** This is the lowest layer, responsible for the actual data retrieval. It consists of `Client` implementations that communicate with external sources. For the dashboard, this means either an `HttpDataClient` that makes requests to the API server or an `InMemoryDataClient` used for the demo environment. - - - -### Core Principles - -- **Dependency Injection:** Repositories and other services are provided to the widget tree using `RepositoryProvider` and `BlocProvider`. This decouples our components and makes them highly testable. -- **Immutability:** All data models and BLoC states are immutable, which leads to more predictable state management and reduces the risk of side effects. -- **Shared Packages:** The dashboard leverages a suite of shared packages for core functionality (e.g., `core`, `data_repository`, `auth_repository`, `ui_kit`). This promotes code reuse and consistency across the entire project ecosystem. diff --git a/src/content/docs/web-dashboard/deployment.mdx b/src/content/docs/web-dashboard/deployment.mdx index 3f0bfc1..26a94b3 100644 --- a/src/content/docs/web-dashboard/deployment.mdx +++ b/src/content/docs/web-dashboard/deployment.mdx @@ -5,16 +5,18 @@ description: A guide to building and deploying the Flutter web dashboard to a pr import { Steps, Aside } from '@astrojs/starlight/components'; -This guide outlines the process for deploying the Flutter News App Web Dashboard. +This guide outlines the process for deploying the Flutter News App Web Dashboard to a production environment. - -1. **Configure for Production** +### Pre-Deployment Configuration + +Before you can build the dashboard for production, you must configure it to connect to your live API server. - Before building, you must configure the dashboard to connect to your live production API. + +1. **Set the Production Environment** - Open the file `lib/main.dart`. - Locate the `appEnvironment` constant. @@ -25,17 +27,17 @@ To ensure you have the most reliable and up-to-date instructions, this guide wil const appEnvironment = AppEnvironment.production; ``` - +2. **Verify the API Base URL** -2. **Follow the Official Flutter Deployment Guide** + - 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/). - The Flutter team provides a comprehensive guide that covers everything you need to know about building and deploying a Flutter web application. This includes compiling your Dart code to JavaScript and deploying the output to various hosting services. + - Please follow the official guide here: - **[Build and release a web app](https://flutter.dev/docs/deployment/web)** +### Building and Deploying - This guide will walk you through the `flutter build web` command and provide best practices for hosting the contents of the generated `build/web` directory. +Once your configuration is ready, you can proceed with building and deploying the application. The official Flutter documentation provides a comprehensive guide that covers compiling your Dart code to JavaScript and deploying the output to various hosting services. - +Following the official guide is the recommended and most reliable path to a successful deployment. + +**[Official Guide: Build and release a web app](https://flutter.dev/docs/deployment/web)** diff --git a/src/content/docs/web-dashboard/features/index.mdx b/src/content/docs/web-dashboard/features/index.mdx new file mode 100644 index 0000000..b4af530 --- /dev/null +++ b/src/content/docs/web-dashboard/features/index.mdx @@ -0,0 +1,27 @@ +--- +title: Features +description: Explore the key features and architecture of the Web Dashboard. +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +The Web Dashboard is packed with features designed for administrators and content publishers. Explore the guides below to understand its core capabilities. + + + + An explanation of the main dashboard screen, its analytics, and quick actions. + [Read more →](/docs/web-dashboard/features/dashboard-overview/) + + + How to create, read, update, and delete your application content. + [Read more →](/docs/web-dashboard/features/content-management/) + + + How to remotely manage the behavior and settings of the mobile application. + [Read more →](/docs/web-dashboard/features/app-configuration/) + + + An overview of the secure sign-in process for the web dashboard. + [Read more →](/docs/web-dashboard/features/authentication/) + + diff --git a/src/content/docs/web-dashboard/guides/index.mdx b/src/content/docs/web-dashboard/guides/index.mdx new file mode 100644 index 0000000..81e6478 --- /dev/null +++ b/src/content/docs/web-dashboard/guides/index.mdx @@ -0,0 +1,19 @@ +--- +title: Developer Guides +description: Practical guides for developers on theming, customization, and localization for the web dashboard. +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +This section provides practical, step-by-step guides for developers working on the web dashboard. + + + + A developer's guide to customizing the visual appearance of the web dashboard. + [Read more →](/docs/web-dashboard/guides/theming-and-customization/) + + + A guide to adding new languages and translations to the web client. + [Read more →](/docs/web-dashboard/guides/localization/) + + diff --git a/src/content/docs/web-dashboard/index.mdx b/src/content/docs/web-dashboard/index.mdx index 833bf1d..ab34400 100644 --- a/src/content/docs/web-dashboard/index.mdx +++ b/src/content/docs/web-dashboard/index.mdx @@ -1,11 +1,11 @@ --- title: 'Web Dashboard: Introduction' -description: An overview of the Flutter News App Web Dashboard, the central control panel for your news ecosystem. +description: An overview of the Flutter News App Web Dashboard, the central control panel for your news toolkit. --- -import { Card, CardGrid, LinkButton } from '@astrojs/starlight/components'; +import { Card, CardGrid } from '@astrojs/starlight/components'; -The Flutter News App Web Dashboard is a comprehensive, production-ready web application built with Flutter. It serves as the central control panel for your entire news ecosystem, providing administrators and content publishers with the tools they need to manage content, configure the mobile app's behavior, and monitor key statistics. +The Web Dashboard is a comprehensive, production-ready web application built with Flutter. It serves as the central control panel for your entire news toolkit, providing administrators and content publishers with the tools they need to manage content, configure the mobile app's behavior, and monitor key statistics. @@ -18,18 +18,18 @@ The Flutter News App Web Dashboard is a comprehensive, production-ready web appl Explore the key features, from content management to remote app configuration. - [Read more →](/docs/web-dashboard/features/dashboard-overview/) + [Read more →](/docs/web-dashboard/features/) - + Understand the architecture, state management, and navigation patterns. - [Read more →](/docs/web-dashboard/architecture/overview/) + [Read more →](/docs/web-dashboard/architecture/) Practical guides for developers on theming, customization, and localization. - [Read more →](/docs/web-dashboard/guides/theming-and-customization/) + [Read more →](/docs/web-dashboard/guides/) User-focused manuals for administrators and publishers. - [Read more →](/docs/web-dashboard/manuals/managing-content/) + [Read more →](/docs/web-dashboard/manuals/) diff --git a/src/content/docs/web-dashboard/manuals/index.mdx b/src/content/docs/web-dashboard/manuals/index.mdx new file mode 100644 index 0000000..f261cf1 --- /dev/null +++ b/src/content/docs/web-dashboard/manuals/index.mdx @@ -0,0 +1,19 @@ +--- +title: User Manuals +description: User-focused manuals for administrators and publishers using the web dashboard. +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +This section provides user-focused manuals for administrators and publishers. + + + + A user manual for creating, editing, and deleting content in the web dashboard. + [Read more →](/docs/web-dashboard/manuals/managing-content/) + + + A user manual for remotely configuring the mobile app from the web dashboard. + [Read more →](/docs/web-dashboard/manuals/configuring-the-app/) + +