-
Notifications
You must be signed in to change notification settings - Fork 0
Final polish #8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Final polish #8
Changes from all commits
Commits
Show all changes
21 commits
Select commit
Hold shift + click to select a range
ff20633
refactor(docs): reorganize content directory and simplify file names
fulleni 48f7775
refactor(sidebar): update sidebar structure and links
fulleni f662b49
docs: update landing page content and structure
fulleni 4085913
docs(core-philosophy): expand content to detail production-ready prin...
fulleni d902c78
docs: add explanation of how the toolkit components fit together
fulleni 9b02ec4
docs: remove introduction.mdx file
fulleni a975778
docs(deployment): streamline content and remove redundant information
fulleni 09279bd
docs(local-setup): improve clarity and flow of local setup guide
fulleni 04f97ad
docs(api-server): update content and structure for clarity and compre...
fulleni cd1a925
docs(api-server): update deployment guide
fulleni 60cad29
docs(email-client): update implementation guide for custom email clients
fulleni c3a23aa
docs(mobile-client): update deployment guide for clarity and focus
fulleni d897b34
docs(mobile-client): revamp introduction page with new structure and ...
fulleni c9d6eba
docs(web-dashboard): update content and links for introduction page
fulleni 904ce15
docs(web-dashboard): refine deployment guide
fulleni 54e0a4c
docs(sidebar): remove introduction from sidebar links
fulleni 886136c
refactor(docs): rename web dashboard architecture overview file to in...
fulleni 1454c0f
docs(sidebars): update architecture overview link in sidebar
fulleni b554bc7
docs(mobile-client): add features overview page
fulleni 04b1ac3
docs(mobile-client): add guides index page
fulleni 790f82b
docs(web-dashboard): refactor architecture page and add new content
fulleni File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
42 changes: 18 additions & 24 deletions
src/content/docs/api-server/deployment.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). | ||
fulleni marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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). | ||
fulleni marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| </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)** | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
48 changes: 48 additions & 0 deletions
src/content/docs/core-philosophy.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
8 changes: 4 additions & 4 deletions
...ent/docs/start-here/deployment-guides.mdx → src/content/docs/deployment.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.