# Application Overview: Krow Staff Mobile App

## 1. Executive Summary
The **Krow Staff App** is the mobile companion for the workforce—the people picking up shifts and performing the work. It operates as a "gig economy" platform where individuals can find flexible work, manage their schedule, and track their income.

For a staff member (e.g., a waiter, chef, or event security), this app is their digital office. They use it to:
*   Browse and apply for available shifts in their area.
*   Manage their professional profile (skills, certificates, experience).
*   Complete pre-shift compliance checks (uniform, equipment).
*   Check in and out of job sites (using QR codes or NFC).
*   Track their earnings and payment history.

## 2. High-Level Architecture
Like the Client App, this application is built on a **Modern Mobile Architecture** that prioritizes offline resilience and real-time accuracy.

*   **The Frontend (The App):** A polished, user-friendly interface that guides staff through complex workflows (like onboarding or shift execution) simply.
*   **The Bridge (API Layer):** Communicates with the Krow Cloud via **GraphQL**, allowing the app to fetch personalized job feeds and update work status efficiently.
*   **The Backend (The Engine):** Manages the "marketplace" logic—matching staff skills to event requirements, calculating pay rates, and processing compliance rules.

## 3. Major Components & Modules
The app is structured into "Features" (functional areas) and "Core" (shared tools), ensuring a clean separation of concerns.

### A. Features (`lib/features/`)
These modules handle the specific tasks a staff member needs to perform:

*   **auth**: Handles existing user login, ensuring secure access to personal data.
*   **check_list**: A compliance tool that ensures staff are "job-ready." It likely includes steps for verifying uniform, equipment, or health and safety requirements before a shift begins.
*   **earning**: The financial dashboard where staff can see their total earnings, payment history, and details for specific pay periods.
*   **home**: The main landing page, likely summarizing upcoming shifts, active jobs, and quick actions.
*   **profile**: Manages the user's professional identity, including their skills, certificates, bio, and account settings.
*   **qr_scanner**: A critical operational tool used for "Clocking In" and "Clocking Out" at the venue, providing digital proof of presence.
*   **shifts**: The core marketplace and schedule manager. It allows staff to:
    *   **Browse:** See available shifts ("Open Jobs").
    *   **Manage:** View accepted shifts ("My Schedule").
    *   **Execute:** See details for the current shift (address, contacts).
*   **sign_up**: A dedicated onboarding flow for new users, guiding them through registration, profile creation, and initial verification.
*   **splash**: The app's entry point, handling initialization, updates, and authentication checks.
*   **support**: Provides access to help resources or direct support channels for resolving issues.

## 4. Component Responsibilities
*   **User Interface (UI):** Focused on clarity and speed. It presents job opportunities attractively and makes the "Clock-In" process frictionless.
*   **State Management (BLoC):** Handles the logic of the app. For example, when a user scans a QR code, the BLoC validates the scan, sends the timestamp to the server, and updates the UI to "Shift Started" mode.
*   **Data Repository:** intelligent data handling. It knows when to fetch new jobs from the internet and when to show the saved schedule from the local database (crucial for venues with poor reception).

## 5. External System Communication
*   **The Krow Backend (GraphQL):** The central authority for job listings, user profiles, and time/attendance records.
*   **Firebase Auth:** Secure identity management for login and signup.
*   **Firebase Remote Config:** Allows dynamic updates to app behavior (e.g., maintenance mode messages).
*   **Geolocation & Maps:** Verifies that the staff member is physically at the venue when clocking in and provides directions to the job site.
*   **Camera/NFC:** Hardware access for scanning QR codes or interacting with NFC tags for check-ins.

## 6. Architectural Patterns
The app adheres to **Clean Architecture** with **BLoC**, ensuring long-term maintainability.

*   **Separation of Concerns:** The code that draws the "Accept Shift" button is completely separate from the code that sends the "Accept" message to the internet.
*   **Reactive UI:** The interface automatically reacts to changes in state (e.g., a new job appearing) without manual refreshing.

## 7. Key Design Decisions & Impact

### A. Offline-First Approach
*   **Decision:** Critical data (like "My Schedule") is cached locally.
*   **Why it matters:** Event venues often have bad signal (basements, remote fields). Staff must still be able to see where they need to be and valid their start time even if the internet drops.

### B. Strict Compliance Checks (`check_list`)
*   **Decision:** Forcing a checklist flow before a shift can start.
*   **Why it matters:** Ensures quality control for the business client. The app acts as a remote manager, ensuring the staff member confirms they have their uniform before they walk in the door.

### C. Feature-Based Folder Structure
*   **Decision:** Grouping files by `feature` (e.g., `earning`, `shifts`) rather than by type (e.g., `screens`, `controllers`).
*   **Why it matters:** Makes the codebase easy to navigate for new developers. If there is a bug with payments, you go straight to the `earning` folder.

## 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 [Staff Mobile App]
        direction TB

        subgraph Features [Feature Modules]
            direction TB
            Auth[Auth & Sign Up]:::frontend
            Shifts[Shift Marketplace & Schedule]:::frontend
            CheckList[Compliance & Uniform Checks]:::frontend
            QR_NFC[QR Scanner & Clock-In]:::frontend
            Earnings[Earnings & History]:::frontend
            Profile[Profile & Skills]:::frontend
        end

        subgraph Core_Logic [Business Logic Layer]
            direction TB
            BLoC[State Management BLoC]:::logic
            Validation[Rules Engine]:::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
        Geo_Maps[Geolocation & Maps]:::external
        Hardware[Camera & NFC Hardware]:::external
    end

    %% Connections
    Auth --> BLoC
    Shifts --> BLoC
    CheckList --> BLoC
    QR_NFC --> BLoC
    Earnings --> BLoC
    Profile --> BLoC

    BLoC --> Validation
    BLoC <--> Repos

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

    API_Client <-->|GraphQL| Krow_Backend
    Repos <-->|Auth & Config| Firebase
    Repos <-->|Location| Geo_Maps
    QR_NFC -.->|Scan| Hardware
```