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

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

7.5 KiB Raw Blame History