Krow-workspace/apps/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.

graph TD
    subgraph "Apps (Entry Points)"
        ClientApp[apps/client]
        StaffApp[apps/staff]
    end

    subgraph "Features (Presentation & Application)"
        ClientFeature[packages/features/client/jobs]
        StaffFeature[packages/features/staff/schedule]
        SharedFeature[packages/features/shared/auth]
    end

    subgraph "Interface Adapters"
        DataConnect[packages/data_connect]
        DesignSystem[packages/design_system]
    end

    subgraph "Core Domain"
        Domain[packages/domain]
        Core[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/)

• 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 (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 (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 (packages/data_connect)

• 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.

2.5 Design System (packages/design_system)

• Role: Visual language and component library.
• Responsibilities:
  • UI components if needed. But mostly try to modify the theme file (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 packages/design_system/widgets.
  • Theme definitions (Colors, Typography).
  • Assets (Icons, Images).
  • More details on how to use this package is available in the 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 docs/03-design-system-usage.md.

2.6 Core (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: packages/domain knows NOTHING about the outer world. It defines what needs to be done, not how.
2. UI Agnosticism: packages/features depends on packages/design_system for looks and packages/domain for logic. It does NOT know about Firebase.
3. Data Isolation: packages/data_connect depends on 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 packages/domain.
2. Mock Implementation:
   • Inside 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 packages/data_connect.
4. Injection: 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).