docs(core-philosophy): expand content to detail production-ready principles

- Add explanation of "Make it Right" principle
- Describe clean, layered architecture
- Include information on standardized and predictable code
- Update title and description for more clarity

Author: fulleni

src/content/docs/core-philosophy.mdx

@@ -1,6 +1,48 @@
 ---
-title: 'Core Philosophy'
-description: The architectural principles behind the API server.
+title: 'Core Philosophy: Built for Production'
+description: An overview of the architectural principles that ensure the toolkit is robust, maintainable, and scalable.
 ---
 
-This page will detail the core architectural philosophies of the project, such as Clean Code, SOLID principles, and the focus on maintainability and extensibility.
+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.