# Application Overview: KROW Client Mobile App

## 1. Executive Summary
The **KROW Client App** is a mobile workforce management tool designed for business owners and managers. Think of it as a "control center" that allows businesses to easily hire, manage, and pay temporary staff for events or shifts.

Instead of calling agencies or managing spreadsheets, a business user opens this app to:
*   Define a job (Event/Shift).
*   Request specific roles (e.g., Waiter, Security).
*   Monitor staff check-ins and attendance.
*   Rate staff performance.
*   Handle payments and invoices.

## 2. High-Level Architecture
The application follows a **Modern Mobile Architecture** designed for reliability and speed. It acts as a "smart interface" that connects the user to the central KROW platform.

*   **The Frontend (This App):** Handles everything the user sees and touches. It validates inputs (like ensuring a shift end time is after the start time) and displays data beautifully.
*   **The Bridge (API Layer):** The app talks to the KROW Cloud Server using **GraphQL**. This allows the app to ask for exactly the data it needs—no more, no less—making it fast even on slower connections.
*   **The Backend (The Brain):** All heavy processing (matching staff to jobs, processing payments) happens on the secure server, not on the phone.

## 3. Major Components & Modules

The application codebase is structured into two main directories: **Features** (Business Capabilities) and **Core** (Shared Utilities & Foundations).

### A. Features (`lib/features/`)
These modules contain the specific business logic and UI for each distinct part of the application:

*   **assigned_staff_screen**: Manages the view where clients can see staff members assigned to their shifts.
*   **clock_manual**: Handles the functionality for manually logging staff work hours (Clock-In/Clock-Out) if automated methods fail or are not used.
*   **create_event**: The workflow and forms for creating new events and defining shift requirements.
*   **events**: The dashboard and list views for managing existing events (upcoming, active, and past).
*   **home**: The main landing screen after login, providing a summary and quick access to key actions.
*   **hubs**: Manages the creation and configuration of "Hubs" (locations) and "Departments".
*   **invoice**: Handles the display and management of billing, invoices, and payment history.
*   **notificatins**: Manages the in-app notification center (alerts, updates, and messages).
*   **profile**: User settings, personal information, and business profile management.
*   **rate_staff**: The interface for clients to provide ratings and feedback on staff performance after a shift.
*   **sign_in**: Handles the authentication flow, including login screens and credential validation.
*   **splash**: The initial launch screen that handles app initialization and auth checks.

## 4. Component Responsibilities
*   **User Interface (UI):** The "Face" of the app. It displays buttons, lists, and forms. It is "dumb" in that it doesn't make decisions; it just shows what it's told.
*   **State Management (BLoC):** The "Brain" of the app. When a user taps "Create Event," this component checks if the form is valid, formats the data, and decides what loading spinner to show.
*   **Data Repository:** The "Librarian." It decides where to get information. Does the app already have the list of staff saved on the phone? Or does it need to fetch a fresh list from the server?

## 5. External System Communication
The app does not live in isolation; it talks to several outside services:

*   **The KROW Backend (GraphQL):** The primary source of truth for all data (Events, Staff profiles, Shifts).
*   **Firebase Auth:** Handles secure login (passwords, email verification) so the KROW team doesn't have to build security from scratch.
*   **Firebase Remote Config:** Allows the KROW team to change app settings (like feature flags or text) without forcing users to update the app.
*   **NFC Services:** Interacts with physical NFC tags, likely for scanning staff badges or verifying presence at a location.
*   **Geolocation Services:** Uses the phone's GPS to verify that actions (like creating a hub) are happening at the correct physical address.

## 6. Architectural Patterns
The app uses a **Feature-First, Clean Architecture** approach combined with **BLoC (Business Logic Component)**.

*   **Feature-First:** The code is organized by *business capability* (e.g., "Invoices", "Events") rather than technical type. This means if we need to change how Invoices work, we go to the "Invoice" folder, and everything is there.
*   **Clean Architecture:** The app is built in layers like an onion. The inner layers (Business Logic) don't know anything about the outer layers (UI). This makes the app highly testable and stable.
*   **BLoC:** This pattern strictly separates "Events" (user clicks) from "States" (what the screen shows). It ensures that a glitch in the UI doesn't crash the business logic.

## 7. Key Design Decisions & Impact

### A. GraphQL over REST
*   **Decision:** The app asks for specific data trees (e.g., "Give me Event X, its Shifts, and only the Names of assigned staff").
*   **Why it matters:** This reduces data usage and loading times. The app doesn't download unnecessary info, making it feel snappier.

### B. Offline Capability (Hive)
*   **Decision:** The app uses a local database (`hive`) to store some data on the phone.
*   **Why it matters:** If the manager loses internet briefly, the app doesn't go blank. It can show cached data until the connection is restored.

### C. Dependency Injection (`injectable`)
*   **Decision:** The app uses a system to "plug in" different tools automatically.
*   **Why it matters:** It makes the app easy to update. If we want to swap the Geolocation provider, we change it in one place, and the whole app updates automatically.

## 8. Overview Diagram
```mermaid
flowchart TD
    %% Define Styles
    classDef frontend fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef logic fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
    classDef data fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c

    subgraph User_Device [Client Mobile App]
        direction TB

        subgraph Features [Feature Modules]
            direction TB
            Auth[Sign In & Profile]:::frontend
            Hubs[Hubs & Business Mgmt]:::frontend
            Events[Event & Shift Mgmt]:::frontend
            Staff[Staff Interaction & Rating]:::frontend
            Finance[Invoices & Payments]:::frontend
        end

        subgraph Core_Logic [Business Logic Layer]
            direction TB
            BLoC[State Management BLoC]:::logic
            Validation[Input Validation]:::logic
        end

        subgraph Data_Layer [Data & Storage]
            direction TB
            Repos[Repositories]:::data
            LocalDB[(Local Storage - Hive)]:::data
            API_Client[GraphQL Client]:::data
        end
    end

    subgraph External_Services [External Cloud Ecosystem]
        direction TB
        Krow_Backend[KROW Backend Server]:::external
        Firebase[Firebase Auth & Config]:::external
        Maps_NFC[Geolocation & NFC Services]:::external
    end

    %% Connections
    Auth --> BLoC
    Hubs --> BLoC
    Events --> BLoC
    Staff --> BLoC
    Finance --> BLoC

    BLoC --> Validation
    BLoC <--> Repos

    Repos <--> LocalDB
    Repos <--> API_Client

    API_Client <-->|GraphQL| Krow_Backend
    Repos <-->|Auth & Config| Firebase
    Repos <-->|Location & Scan| Maps_NFC
```