Add initial mobile app prototypes and staff payments feature

Introduces the first versions of client and staff mobile application prototypes, including platform-specific assets, screens, and configuration for Android, iOS, macOS, Linux, and Windows. Adds documentation, AI prompt guides, and a new staff payments feature module with repository, use cases, and presentation logic. Also includes generated localization files and supporting resources for both client and staff apps.
2026-01-25 17:01:18 -05:00
parent 0b043ed91e
commit 19959a2b3f
468 changed files with 71399 additions and 0 deletions
--- a/apps/mobile/docs/01-architecture-principles.md
+++ b/apps/mobile/docs/01-architecture-principles.md
@@ -0,0 +1,135 @@
+# KROW Architecture Principles
+
+This document is the **AUTHORITATIVE** source of truth for the KROW engineering architecture.
+All agents and engineers must adhere strictly to these principles. Deviations are interpreted as errors.
+
+## 1. High-Level Architecture
+
+The KROW platform follows a strict **Clean Architecture** implementation within a **Melos Monorepo**.
+Dependencies flow **inwards** towards the Domain.
+
+```mermaid
+graph TD
+    subgraph "Apps (Entry Points)"
+        ClientApp[apps/mobile/apps/client]
+        StaffApp[apps/mobile/apps/staff]
+    end
+
+    subgraph "Features (Presentation & Application)"
+        ClientFeature[apps/mobile/packages/features/client/jobs]
+        StaffFeature[apps/mobile/packages/features/staff/schedule]
+        SharedFeature[apps/mobile/packages/features/shared/auth]
+    end
+
+    subgraph "Interface Adapters"
+        DataConnect[apps/mobile/packages/data_connect]
+        DesignSystem[apps/mobile/packages/design_system]
+    end
+
+    subgraph "Core Domain"
+        Domain[apps/mobile/packages/domain]
+        Core[apps/mobile/packages/core]
+    end
+
+    %% Dependency Flow
+    ClientApp --> ClientFeature & SharedFeature
+    StaffApp --> StaffFeature & SharedFeature
+    ClientApp --> DataConnect
+    StaffApp --> DataConnect
+
+    ClientFeature & StaffFeature & SharedFeature --> Domain
+    ClientFeature & StaffFeature & SharedFeature --> DesignSystem
+    ClientFeature & StaffFeature & SharedFeature --> Core
+
+    DataConnect --> Domain
+    DataConnect --> Core
+    DesignSystem --> Core
+    Domain --> Core
+
+    %% Strict Barriers
+    linkStyle default stroke-width:2px,fill:none,stroke:gray
+```
+
+## 2. Repository Structure & Package Roles
+
+### 2.1 Apps (`apps/mobile/apps/`)
+- **Role**: Application entry points and Dependency Injection (DI) roots.
+- **Responsibilities**:
+  - Initialize Flutter Modular.
+  - Assemble features into a navigation tree.
+  - Inject concrete implementations (from `data_connect`) into Feature packages.
+  - Configure environment-specific settings.
+- **RESTRICTION**: NO business logic. NO UI widgets (except `App` and `Main`).
+
+### 2.2 Features (`apps/mobile/packages/features/<APP_NAME>/<FEATURE_NAME>`)
+- **Role**: Vertical slices of user-facing functionality.
+- **Internal Structure**:
+  - `domain/`: Feature-specific Use Cases and Repository Interfaces.
+  - `data/`: Repository Implementations.
+  - `presentation/`: 
+    - Pages, BLoCs, Widgets.
+    - For performance make the pages as `StatelessWidget` and move the state management to the BLoC or `StatefulWidget` to an external separate widget file.
+- **Responsibilities**:
+  - **Presentation**: UI Pages, Modular Routes.
+  - **State Management**: BLoCs / Cubits.
+  - **Application Logic**: Use Cases.
+- **RESTRICTION**: Features MUST NOT import other features. Communication happens via shared domain events.
+
+### 2.3 Domain (`apps/mobile/packages/domain`)
+- **Role**: The stable heart of the system. Pure Dart.
+- **Responsibilities**:
+  - **Entities**: Immutable data models (Data Classes).
+  - **Failures**: Domain-specific error types.
+- **RESTRICTION**: NO Flutter dependencies. NO `json_annotation`. NO package dependencies (except `equatable`).
+
+### 2.4 Data Connect (`apps/mobile/packages/data_connect/lib/src/mocks`)
+- **Role**: Interface Adapter for Backend Access (Datasource Layer).
+- **Responsibilities**:
+  - Implement low-level Datasources or generated SDK wrappers.
+  - map Domain Entities to/from Firebase Data Connect generated code.
+  - Handle Firebase exceptions.
+  - For now use the mock repositories to connect to the features, not the dataconnect_generated.
+
+### 2.5 Design System (`apps/mobile/packages/design_system`)
+- **Role**: Visual language and component library.
+- **Responsibilities**:
+  - UI components if needed. But mostly try to modify the theme file (apps/mobile/packages/design_system/lib/src/ui_theme.dart) so we can directly use the theme in the app, to use the default material widgets.
+    - If not possible, and if that specific widget is used in multiple features, then try to create a shared widget in the `apps/mobile/packages/design_system/widgets`.
+  - Theme definitions (Colors, Typography).
+  - Assets (Icons, Images).
+  - More details on how to use this package is available in the `apps/mobile/docs/03-design-system-usage.md`.
+- **RESTRICTION**: 
+  - CANNOT change colours or typography.
+  - Dumb widgets only. NO business logic. NO state management (Bloc).
+  - More details on how to use this package is available in the `apps/mobile/docs/03-design-system-usage.md`.
+
+### 2.6 Core (`apps/mobile/packages/core`)
+- **Role**: Cross-cutting concerns.
+- **Responsibilities**:
+  - Extension methods.
+  - Logger configuration.
+  - Base classes for Use Cases or Result types (functional error handling).
+
+## 3. Dependency Direction & Boundaries
+
+1.  **Domain Independence**: `apps/mobile/packages/domain` knows NOTHING about the outer world. It defines *what* needs to be done, not *how*.
+2.  **UI Agnosticism**: `apps/mobile/packages/features` depends on `apps/mobile/packages/design_system` for looks and `apps/mobile/packages/domain` for logic. It does NOT know about Firebase.
+3.  **Data Isolation**: `apps/mobile/packages/data_connect` depends on `apps/mobile/packages/domain` to know what interfaces to implement. It does NOT know about the UI.
+
+## 4. Firebase Data Connect Strategy
+
+Since Firebase Data Connect code does not yet exist, we adhere to a **Strict Mocking Strategy**:
+
+1.  **Interface First**: All data requirements are first defined as `abstract interface class IRepository` in `apps/mobile/packages/domain`.
+2.  **Mock Implementation**:
+    -   Inside `apps/mobile/packages/data_connect`, create a `MockRepository` implementation.
+    -   Use in-memory lists or hardcoded futures to simulate backend responses.
+    -   **CRITICAL**: Do NOT put mocks in `test/` folders if they are needed to run the app in "dev" mode. Put them in `lib/src/mocks/`.
+3.  **Future Integration**: When Data Connect is ready, we will add `RealRepository` in `apps/mobile/packages/data_connect`.
+4.  **Injection**: `apps/mobile/apps/` will inject either `MockRepository` or `RealRepository` based on build flags or environment variables.
+
+## 5. Feature Isolation
+
+-   **Zero Direct Imports**: `import 'package:feature_a/...'` is FORBIDDEN inside `package:feature_b`.
+-   **Navigation**: Use string-based routes or a shared route definition module in `core` (if absolutely necessary) to navigate between features.
+-   **Data Sharing**: Features do not share state directly. They share data via the underlying `Domain` repositories (e.g., both observe the same `User` stream from `AuthRepository`).