Krow-workspace/apps/mobile/docs/01-architecture-principles.md

# 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`).