Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0c33339ef73cea55bdbf67180122efd8c422afd
Krow-workspace/docs/MOBILE/01-architecture-principles.md

9.8 KiB
Raw Blame History

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/mobile/apps/client"]
        StaffApp["apps/mobile/apps/staff"]
    end

    subgraph "Features"
        ClientFeatures["apps/mobile/packages/features/client/*"]
        StaffFeatures["apps/mobile/packages/features/staff/*"]
    end

    subgraph "Services"
        DataConnect["apps/mobile/packages/data_connect"]
        DesignSystem["apps/mobile/packages/design_system"]
        CoreLocalization["apps/mobile/packages/core_localization"]
    end

    subgraph "Core Domain"
        Domain["apps/mobile/packages/domain"]
        Core["apps/mobile/packages/core"]
    end

    %% Dependency Flow
    ClientApp --> ClientFeatures & DataConnect & CoreLocalization
    StaffApp --> StaffFeatures & DataConnect & CoreLocalization

    ClientFeatures & StaffFeatures --> Domain
    ClientFeatures & StaffFeatures --> DesignSystem
    ClientFeatures & StaffFeatures --> CoreLocalization
    ClientFeatures & StaffFeatures --> Core

    DataConnect --> Domain
    DataConnect --> Core
    DesignSystem --> Core
    CoreLocalization --> 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(always extend the apps/mobile/packages/core/lib/src/domain/usecases/usecase.dart abstract clas) 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)

  • Role: Interface Adapter for Backend Access (Datasource Layer).
  • Responsibilities:
    • Implement Firebase Data Connect connector and service layer.
    • Map Domain Entities to/from Data Connect generated code.
    • Handle Firebase exceptions and map to domain failures.
    • Provide centralized DataConnectService with session management.

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 Localization (apps/mobile/packages/core_localization)

  • Role: Centralized language and localization management.
  • Responsibilities:
    • Define all user-facing strings in l10n/ with i18n tooling support
    • Provide LocaleBloc for reactive locale state management
    • Export TranslationProvider for BuildContext-based string access
    • Map domain failures to user-friendly localized error messages via ErrorTranslator
  • Feature Integration:
    • Features access strings via context.strings.<key> in presentation layer
    • BLoCs don't depend on localization; they emit domain failures
    • Error translation happens in UI layer (pages/widgets)
  • App Integration:
    • Apps import LocalizationModule() in their module imports
    • Apps wrap the material app with BlocProvider<LocaleBloc>() and TranslationProvider
    • Apps initialize MaterialApp with locale from LocaleState

2.7 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. Data Connect Service & Session Management

All backend access is unified through DataConnectService with integrated session management:

4.1 Session Handler Mixin

  • Location: apps/mobile/packages/data_connect/lib/src/services/mixins/session_handler_mixin.dart
  • Responsibilities:
    • Automatic token refresh (triggered when token <5 minutes to expiry)
    • Firebase auth state listening
    • Role-based access validation
    • Session state stream emissions
    • 3-attempt retry logic with exponential backoff on token validation failure
  • Key Method: initializeAuthListener(allowedRoles: [...]) - call once on app startup

4.2 Session Listener Widget

  • Location: apps/mobile/apps/<app>/lib/src/widgets/session_listener.dart
  • Responsibilities:
    • Wraps entire app to listen to session state changes
    • Shows user-friendly dialogs for session expiration/errors
    • Handles navigation on auth state changes
  • Pattern: SessionListener(child: AppWidget())

4.3 Repository Pattern with Data Connect

  1. Interface First: Define abstract interface class <Name>RepositoryInterface in feature domain layer.
  2. Implementation: Use _service.run() wrapper that automatically:
    • Validates user is authenticated (if required)
    • Ensures token is valid and refreshes if needed
    • Executes the Data Connect query
    • Handles exceptions and maps to domain failures
  3. Session Store Population: On successful auth, session stores are populated:
    • Staff: StaffSessionStore.instance.setSession(StaffSession(...))
    • Client: ClientSessionStore.instance.setSession(ClientSession(...))
  4. Lazy Loading: If session is null, fetch data via getStaffById() or getBusinessById() and update store.

5. Feature Isolation & Cross-Feature Communication

  • Zero Direct Imports: import 'package:feature_a/...' is FORBIDDEN inside package:feature_b.
    • Exception: Shared packages like domain, core, and design_system are always accessible.
  • Navigation: Use named routes via Flutter Modular:
    • Pattern: Modular.to.navigate('route_name')
    • Configuration: Routes defined in module.dart files; constants in paths.dart
  • Data Sharing: Features do not share state directly. Shared data accessed through:
    • Domain Repositories: Centralized data sources (e.g., AuthRepository)
    • Session Stores: StaffSessionStore and ClientSessionStore for app-wide user context
    • Event Streams: If needed, via DataConnectService streams for reactive updates

6. App-Specific Session Management

Each app (staff and client) has different role requirements and session patterns:

6.1 Staff App Session

  • Location: apps/mobile/apps/staff/lib/main.dart
  • Initialization: DataConnectService.instance.initializeAuthListener(allowedRoles: ['STAFF', 'BOTH'])
  • Session Store: StaffSessionStore with StaffSession(user: User, staff: Staff?, ownerId: String?)
  • Lazy Loading: getStaffName() fetches via getStaffById() if session null
  • Navigation: On auth → Modular.to.toStaffHome(), on unauth → Modular.to.toInitialPage()

6.2 Client App Session

  • Location: apps/mobile/apps/client/lib/main.dart
  • Initialization: DataConnectService.instance.initializeAuthListener(allowedRoles: ['CLIENT', 'BUSINESS', 'BOTH'])
  • Session Store: ClientSessionStore with ClientSession(user: User, business: ClientBusinessSession?)
  • Lazy Loading: getUserSessionData() fetches via getBusinessById() if session null
  • Navigation: On auth → Modular.to.toClientHome(), on unauth → Modular.to.toInitialPage()
Reference in New Issue View Git Blame Copy Permalink