feat: Add comprehensive documentation for Krow Platform architecture, including system bible, web application use cases, and mobile agent development rules

- Introduced the Krow Platform System Bible detailing the executive summary, system vision, ecosystem overview, architecture, application responsibilities, use cases, and security model. - Created a detailed use case overview for the Krow Web Application, outlining workflows for Admin, Client, and Vendor roles. - Established non-negotiable agent development rules for mobile applications, emphasizing file structure, naming conventions, logic placement, localization, and error handling. - Defined architecture principles for the Krow mobile platform, focusing on clean architecture, dependency direction, and session management. - Documented design system usage guidelines to ensure UI consistency and adherence to design tokens across applications.
2026-02-18 10:23:07 -05:00
parent fe87291651
commit f5a23c3aaa
9 changed files with 1477 additions and 2 deletions
--- a/docs/MOBILE/00-agent-development-rules.md
+++ b/docs/MOBILE/00-agent-development-rules.md
@@ -0,0 +1,135 @@
+# Agent Development Rules
+
+These rules are **NON-NEGOTIABLE**. They are designed to prevent architectural degradation by automated agents.
+
+## 1. File Creation & Structure
+
+1.  **Feature-First Packaging**:
+    *   **DO**: Create new features as independent packages in `apps/mobile/packages/features/<app_name>/<feature_name>`.
+    *   **DO NOT**: Add features to `apps/mobile/packages/core` or existing apps directly.
+    *   **DO NOT**: Create cross-feature or cross-app dependencies.
+2.  **Path Conventions**:
+    *   Entities: `apps/mobile/packages/domain/lib/src/entities/<entity>.dart`
+    *   Repositories (Interface): `apps/mobile/packages/features/<app_name>/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart`
+    *   Repositories (Impl): `apps/mobile/packages/features/<app_name>/<feature>/lib/src/data/repositories_impl/<name>_repository_impl.dart`
+    *   Use Cases: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/application/<name>_usecase.dart`
+    *   BLoCs: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/presentation/blocs/<name>_bloc.dart`
+    *   Pages: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/presentation/pages/<name>_page.dart`
+    *   Widgets: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/presentation/widgets/<name>_widget.dart`
+3.  **Barrel Files**:
+    *   **DO**: Use `export` in `lib/<package_name>.dart` only for public APIs.
+    *   **DO NOT**: Export internal implementation details in the main package file.
+
+## 2. Naming Conventions
+
+Follow Dart standards strictly.
+
+| Type | Convention | Example |
+| :--- | :--- | :--- |
+| **Files** | `snake_case` | `user_profile_page.dart` |
+| **Classes** | `PascalCase` | `UserProfilePage` |
+| **Variables** | `camelCase` | `userProfile` |
+| **Interfaces** | terminate with `Interface` | `AuthRepositoryInterface` |
+| **Implementations** | terminate with `Impl` | `AuthRepositoryImpl` |
+
+## 3. Logic Placement (Strict Boundaries)
+
+*   **Business Rules**: MUST reside in **Use Cases** (Domain/Feature Application layer).
+    *   *Forbidden*: Placing business rules in BLoCs or Widgets.
+*   **State Logic**: MUST reside in **BLoCs** or **StatefulWidgets** (only for ephemeral UI state).
+    *   *Forbidden*: `setState` in Pages for complex state management.
+    *   **Recommendation**: Pages should be `StatelessWidget` with state delegated to BLoCs.
+*   **Data Transformation**: MUST reside in **Repositories** (Data Connect layer).
+    *   *Forbidden*: Parsing JSON in the UI or Domain.
+    *   **Pattern**: Repositories map Data Connect models to Domain entities.
+*   **Navigation Logic**: MUST reside in **Flutter Modular Routes**.
+    *   *Forbidden*: `Navigator.push` with hardcoded widgets.
+    *   **Pattern**: Use named routes via `Modular.to.navigate()`.
+*   **Session Management**: MUST reside in **DataConnectService** via **SessionHandlerMixin**.
+    *   **Pattern**: Automatic token refresh, auth state listening, and role-based validation.
+    *   **UI Reaction**: **SessionListener** widget wraps the entire app and responds to session state changes.
+
+## 4. Localization (core_localization) Integration
+
+All user-facing text MUST be localized using the centralized `core_localization` package:
+
+1.  **String Management**: 
+    *   Define all user-facing strings in `apps/mobile/packages/core_localization/lib/src/l10n/`
+    *   Use `slang` or similar i18n tooling for multi-language support
+    *   Access strings in presentation layer via `context.strings.<key>`
+2.  **BLoC Integration**:
+    *   `LocaleBloc` manages the current locale state
+    *   Apps import `core_localization.LocalizationModule()` in their module imports
+    *   Wrap app with `BlocProvider<LocaleBloc>()` to expose locale state globally
+3.  **Feature Usage**:
+    *   Pages and widgets access localized strings: `Text(context.strings.buttonLabel)`
+    *   Build methods receive `BuildContext` with access to current locale
+    *   No hardcoded English strings in feature packages
+4.  **Error Messages**:
+    *   Use `ErrorTranslator` from `core_localization` to map domain failures to user-friendly messages
+    *   **Pattern**: Failures emitted from BLoCs are translated to localized strings in the UI
+
+## 5. Data Connect Integration Strategy
+
+All backend access is centralized through `DataConnectService` in `apps/mobile/packages/data_connect`:
+
+1.  **Repository Interface First**: Define `abstract interface class <Name>RepositoryInterface` in the feature's `domain/repositories/` folder.
+2.  **Repository Implementation**: Implement the interface in `data/repositories_impl/` using `_service.run()` wrapper.
+    *   **Pattern**: `await _service.run(() => connector.<query>().execute())`
+    *   **Benefit**: Automatic auth validation, token refresh, and error handling.
+3.  **Session Handling**: Use `DataConnectService.instance.initializeAuthListener(allowedRoles: [...])` in app main.dart.
+    *   **Automatic**: Token refresh with 5-minute expiry threshold.
+    *   **Retry Logic**: 3 attempts with exponential backoff (1s → 2s → 4s) before emitting error.
+    *   **Role Validation**: Configurable per app (e.g., Staff: `['STAFF', 'BOTH']`, Client: `['CLIENT', 'BUSINESS', 'BOTH']`).
+4.  **Session State Management**: Wrap app with `SessionListener` widget to react to session changes.
+    *   **Dialogs**: Shows session expired or error dialogs for user-facing feedback.
+    *   **Navigation**: Routes to login on session loss, to home on authentication.
+
+## 5. Prototype Migration Rules
+
+You have access to `prototypes/` folders. When migrating code:
+
+1.  **Extract Assets**: 
+    * You MAY copy icons, images, and colors. But they should be tailored to the current design system. Do not change the colours and typgorahys in the design system. They are final. And you have to use these in the UI.
+      * When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the `apps/mobile/docs/03-design-system-usage.md`.
+2.  **Extract Layouts**: You MAY copy `build` methods for UI structure.
+3.  **REJECT Architecture**: You MUST **NOT** copy the `GetX`, `Provider`, or `MVC` patterns often found in prototypes. Refactor immediately to **Bloc + Clean Architecture with Flutter Modular and Melos**.
+
+## 6. Handling Ambiguity
+
+If a user request is vague:
+
+1.  **STOP**: Do not guess domain fields or workflows.
+2.  **ANALYZE**: 
+ - For architecture related questions, refer to `apps/mobile/docs/01-architecture-principles.md` or existing code.
+ - For design system related questions, refer to `apps/mobile/docs/03-design-system-usage.md` or existing code.
+3.  **DOCUMENT**: If you must make an assumption to proceed, add a comment `// ASSUMPTION: <explanation>` and mention it in your final summary.
+4.  **ASK**: Prefer asking the user for clarification on business rules (e.g., "Should a 'Job' have a 'status'?").
+
+## 7. Dependencies
+
+*   **DO NOT** add 3rd party packages without checking `apps/mobile/packages/core` first.
+*   **DO NOT** add `firebase_auth` or `firebase_data_connect` to any Feature package. They belong in `data_connect` only.
+*   **Service Locator**: Use `DataConnectService.instance` for singleton access to backend operations.
+*   **Dependency Injection**: Use Flutter Modular for BLoC and UseCase injection in `Module.routes()`.
+
+## 8. Error Handling
+
+*   **Domain Failures**: Define custom `Failure` classes in `domain/failures/`.
+*   **Data Connect Errors**: Map Data Connect exceptions to Domain failures in repositories.
+*   **User Feedback**: BLoCs emit error states; UI displays snackbars or dialogs.
+*   **Session Errors**: SessionListener automatically shows dialogs for session expiration/errors.
+
+## 9. Testing
+
+*   **Unit Tests**: Test use cases and repositories with real implementations.
+*   **Widget Tests**: Use `WidgetTester` to test UI widgets and BLoCs.
+*   **Integration Tests**: Test full feature flows end-to-end with Data Connect.
+*   **Pattern**: Use dependency injection via Modular to swap implementations if needed for testing.
+
+## 10. Follow Clean Code Principles
+
+* Add doc comments to all classes and methods you create.
+* Keep methods and classes focused and single-responsibility.
+* Use meaningful variable names that reflect intent.
+* Keep widget build methods concise; extract complex widgets to separate files.
--- a/docs/MOBILE/01-architecture-principles.md
+++ b/docs/MOBILE/01-architecture-principles.md
@@ -0,0 +1,197 @@
+# 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"
+        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 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()`
--- a/docs/MOBILE/02-design-system-usage.md
+++ b/docs/MOBILE/02-design-system-usage.md
@@ -0,0 +1,155 @@
+# 03 - Design System Usage Guide
+
+This document defines the mandatory standards for designing and implementing user interfaces across all applications and feature packages using the shared `apps/mobile/packages/design_system`.
+
+## 1. Introduction & Purpose
+
+The Design System is the single source of truth for the visual identity of the project. Its purpose is to ensure UI consistency, reduce development velocity by providing reusable primitives, and eliminate "design drift" across multiple feature teams and applications.
+
+**All UI implementation MUST consume values ONLY from the `design_system` package.**
+
+### Core Principle
+Design tokens (colors, typography, spacing, etc.) are immutable and defined centrally. Features consume these tokens but NEVER modify them. The design system maintains visual coherence across staff and client apps.
+
+## 2. Design System Ownership & Responsibility
+
+- **Centralized Authority**: The `apps/mobile/packages/design_system` is the owner of all brand assets, colors, typography, and core components.
+- **No Local Overrides**: Feature packages (e.g., `staff_authentication`) are consumers. They are prohibited from defining their own global styles or overriding theme values locally.
+- **Extension Policy**: If a required style (color, font, or icon) is missing, the developer must first add it to the `design_system` package following existing patterns before using it in a feature.
+
+## 3. Package Structure Overview (`apps/mobile/packages/design_system`)
+
+The package is organized to separate tokens from implementation:
+- `lib/src/ui_colors.dart`: Color tokens and semantic mappings.
+- `lib/src/ui_typography.dart`: Text styles and font configurations.
+- `lib/src/ui_icons.dart`: Exported icon sets.
+- `lib/src/ui_constants.dart`: Spacing, radius, and elevation tokens.
+- `lib/src/ui_theme.dart`: Centralized `ThemeData` factory.
+- `lib/src/widgets/`: Common "Smart Widgets" and reusable UI building blocks.
+
+## 4. Colors Usage Rules
+
+Feature packages **MUST NOT** define custom hex codes or `Color` constants.
+
+### Usage Protocol
+- **Primary Method**:Use `UiColors` from the design system for specific brand accents.
+- **Naming Matching**: If an exact color is missing, use the closest existing semantic color (e.g., use `UiColors.mutedForeground` instead of a hardcoded grey).
+
+```dart
+// ❌ ANTI-PATTERN: Hardcoded color
+Container(color: Color(0xFF1A2234))
+
+// ✅ CORRECT: Design system token
+Container(color: UiColors.background)
+```
+
+## 5. Typography Usage Rules
+
+Custom `TextStyle` definitions in feature packages are **STRICTLY PROHIBITED**.
+
+### Usage Protocol
+- Use `UiTypography` from the design system for specific brand accents.
+
+```dart
+// ❌ ANTI-PATTERN: Custom TextStyle
+Text('Hello', style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold))
+
+// ✅ CORRECT: Design system typography
+Text('Hello', style: UiTypography.display1m)
+```
+
+## 6. Icons Usage Rules
+
+Feature packages **MUST NOT** import icon libraries (like `lucide_icons`) directly. They should use the icons exposed via `UiIcons`.
+
+- **Standardization**: Ensure the same icon is used for the same action across all features (e.g., always use `UiIcons.chevronLeft` for navigation).
+- **Additions**: New icons must be added to the design system (only using the typedef _IconLib = LucideIcons or typedef _IconLib2 = FontAwesomeIcons; and nothing else) first to ensure they follow the project's stroke weight and sizing standards.
+
+## 7. UI Constants & Layout Rules
+
+Hardcoded padding, margins, and radius values are **PROHIBITED**.
+
+- **Spacing**: Use `UiConstants.spacing` multiplied by tokens (e.g., `S`, `M`, `L`).
+- **Border Radius**: Use `UiConstants.borderRadius`.
+- **Elevation**: Use `UiConstants.elevation`.
+
+```dart
+// ✅ CORRECT: Spacing and Radius constants
+Padding(
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  child: Container(
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+)
+```
+
+## 8. Common Smart Widgets Guidelines
+
+The design system provides "Smart Widgets" – these are high-level UI components that encapsulate both styling and standard behavior.
+
+- **Standard Widgets**: Prefer standard Flutter Material widgets (e.g., `ElevatedButton`) but styled via the central theme.
+- **Custom Components**: Use `design_system` widgets for non-standard elements or wisgets that has similar design across various features, if provided.
+- **Composition**: Prefer composing standard widgets over creating deep inheritance hierarchies in features.
+
+## 9. Theme Configuration & Usage
+
+Applications (`apps/mobile/apps/`) must initialize the theme once in the root `MaterialApp`.
+
+```dart
+MaterialApp.router(
+  theme: StaffTheme.light, // Mandatory: Consumption of centralized theme
+  // ...
+)
+```
+**No application-level theme customization is allowed.**
+
+## 10. Feature Development Workflow (POC → Themed)
+
+To bridge the gap between rapid prototyping (POCs) and production-grade code, developers must follow this three-step workflow:
+
+1. **Step 1: Structural Implementation**: Implement the UI logic and layout **exactly matching the POC**. Hardcoded values from the POC are acceptable in this transient state to ensure visual parity.
+2. **Step 2: Architecture Refactor**: Immediately refactor the code to:
+   - Follow clean architecture principles from `apps/mobile/docs/00-agent-development-rules.md` and `01-architecture-principles.md`
+   - Move business logic from widgets to BLoCs and use cases
+   - Implement proper repository pattern with Data Connect
+   - Use dependency injection via Flutter Modular
+3. **Step 3: Design System Integration**: Immediately refactor UI to consume design system primitives:
+   - Replace hex codes with `UiColors`
+   - Replace manual `TextStyle` with `UiTypography`
+   - Replace hardcoded padding/radius with `UiConstants`
+   - Upgrade icons to design system versions
+   - Use `ThemeData` from `design_system` instead of local theme overrides
+
+## 11. Anti-Patterns & Common Mistakes
+
+- **"Magic Numbers"**: Hardcoding `EdgeInsets.all(12.0)` instead of using design system constants.
+- **Local Themes**: Using `Theme(data: ...)` to override colors for a specific section of a page.
+- **Hex Hunting**: Copy-pasting hex codes from Figma or POCs into feature code.
+- **Package Bypassing**: Importing `package:flutter/material.dart` and ignoring `package:design_system`.
+- **Stateful Pages**: Pages with complex state logic instead of delegating to BLoCs.
+- **Direct Data Queries**: Features querying Data Connect directly instead of through repositories.
+- **Global State**: Using global variables for session/auth instead of `SessionStore` + `SessionListener`.
+- **Hardcoded Routes**: Using `Navigator.push(context, MaterialPageRoute(...))` instead of Modular.
+- **Feature Coupling**: Importing one feature package from another instead of using domain-level interfaces.
+
+## 12. Enforcement & Review Checklist
+
+Before any UI code is merged, it must pass this checklist:
+
+### Design System Compliance
+1. [ ] No hardcoded `Color(...)` or `0xFF...` in the feature package.
+2. [ ] No custom `TextStyle(...)` definitions.
+3. [ ] All spacing/padding/radius uses `UiConstants`.
+4. [ ] All icons are consumed from the approved design system source.
+5. [ ] The feature relies on the global `ThemeData` and does not provide local overrides.
+6. [ ] The layout matches the POC visual intent while using design system primitives.
+
+### Architecture Compliance
+7. [ ] No direct Data Connect queries in widgets; all data access via repositories.
+8. [ ] BLoCs handle all non-trivial state logic; pages are mostly stateless.
+9. [ ] Session/auth accessed via `SessionStore` not global state.
+10. [ ] Navigation uses Flutter Modular named routes.
+11. [ ] Features don't import other feature packages directly.
+12. [ ] All business logic in use cases, not BLoCs or widgets.
+13. [ ] Repositories properly implement error handling and mapping.
+14. [ ] Doc comments present on all public classes and methods.