# Staff Mobile Application: Architecture Overview

## 1. Executive Summary
The **Staff Mobile Application** is the dedicated companion for the temporary workforce. It is designed to be the "one-stop-shop" for workers to find employment, manage their work life, and get paid.

For a worker, this app replaces the traditional agency corkboard and paper timesheets. It allows them to browse available shifts in their area, claim jobs that fit their schedule, clock in and out using their phone, and track their earnings instantly. It also handles all the necessary administrative tasks like tax forms and certifications.

## 2. High-Level Architecture
Like its client-facing counterpart, this application is built on **Flutter**, ensuring a high-quality, native experience on both Android and iOS devices from a single codebase.

The architecture is **User-Centric and Feature-Driven**. It is organized around the daily lifecycle of a worker: finding work, doing work, getting paid, and growing their career.

The system is structured into three main logical layers:
1.  **UI Layer:** The screens and interactive elements (The "Face" of the app).
2.  **Application Logic:** The state management that handles user sessions, shift status, and data updates (The "Brain").
3.  **Data & Service Layer:** The connection to backend systems for authentication, job listings, and payments (The "Backbone").

## 3. Major Components & Modules

### A. Onboarding & Authentication Module
*   **Responsibility:** bringing new workers into the ecosystem securely.
*   **Key Features:** `Get Started`, `Phone Verification` (OTP), and `Profile Setup`.
*   **Purpose:** Verifies identity and collects essential initial information to create a trustable worker profile.

### B. Marketplace (Jobs) Module
*   **Responsibility:** connecting workers with open opportunities.
*   **Key Features:** `Jobs Screen` for browsing open shifts, filtering by location/role, and viewing `Shift Details`.
*   **Purpose:** Acts as the job board where supply meets demand.

### C. Shift Management Module
*   **Responsibility:** managing the "doing" of the work.
*   **Key Features:**
    *   **Shifts:** A personalized schedule of upcoming and past commitments.
    *   **Clock In/Out:** GPS-enabled time tracking to verify attendance.
    *   **Availability:** Tools for workers to set when they can and cannot work.

### D. Financial Module
*   **Responsibility:** handling compensation and benefits.
*   **Key Features:**
    *   **Earnings:** Visual breakdown of income.
    *   **Payments:** Transaction history and bank account management.
    *   **Early Pay:** Feature allowing access to wages before the standard payday.
    *   **Benefits:** Access to worker perks and insurance.

### E. Profile & Compliance Module
*   **Responsibility:** managing the professional identity and legal requirements.
*   **Key Features:**
    *   **Compliance:** Uploading and verifying `Certificates`, `Documents`, and Tax Forms (`I-9`, `W-4`).
    *   **Level Up:** `KROW University` for training and a `Leaderboard` for gamification.
    *   **Support:** `FAQs`, `Privacy`, and `Messages`.

## 4. Component Responsibilities

| Component | Primary Responsibility | Example Task |
| :--- | :--- | :--- |
| **Authentication Screens** | Security & Entry | Validates the 6-digit code sent to the user's phone during login. |
| **Shift Provider** | Data State Management | Keeps track of which shift is currently "Active" so the Clock-In button appears on the Home screen. |
| **Router** | Navigation | Deep-links a user directly to a specific "Shift Detail" page from a push notification. |
| **Mock Service** | Data Simulation | Generates a realistic list of "Available Jobs" nearby for the prototype to display. |

## 5. Data Flow

1.  **Discovery:** The worker opens the `Jobs` screen. The app requests "Available Shifts" from the Data Layer.
2.  **Action:** The worker taps "Accept Shift".
3.  **Processing:** The app updates the shift status locally to "Scheduled" and adds it to the worker's `My Shifts` list.
4.  **Execution:** On the day of the job, the worker opens the `Clock In` screen. The app checks their geolocation.
5.  **Verification:** If the location matches the job site, the "Clock In" action is allowed.
6.  **Completion:** After clocking out, the data flows to the `Earnings` module, updating the "Pending Pay" balance.

## 6. External System Communication

The architecture is designed to interface with several critical external systems:

*   **Identity Services:** For SMS-based phone verification and secure login.
*   **Maps & Geolocation:** Uses device location services to verify "Clock In" actions are performed on-site.
*   **Banking/Payment APIs:** Connects to payment processors for "Early Pay" and direct deposit functions.
*   **Document Verification Services:** (Future State) To automatically validate uploaded IDs and certifications.
*   **Backend Database (Firebase):** Stores the "Single Source of Truth" for user profiles, shift history, and compliance status.

## 7. Architectural Patterns

*   **Feature-First Organization:** The codebase is grouped by feature (e.g., `worker_profile/compliance`, `worker_profile/finances`). This "vertical slice" architecture keeps related code together.
*   **State Management with Riverpod:** Used to manage global application state (like "Is the user logged in?" or "What is my current location?") in a clean, testable way.
*   **Repository Pattern (Implied):** The service layer (`mock_service.dart`) acts as a repository, abstracting the data source so the UI doesn't care if data comes from a mock file or a real server.

## 8. Key Design Decisions

*   **Flutter for Mobile:** Ensures the app is responsive and performs well on the wide variety of devices low-wage workers might own.
*   **Strict Compliance Separation:** Dedicating a specific sub-module to `Compliance` (Tax forms, I-9) highlights the importance of legal adherence in the staffing industry.
*   **Gamification (Level Up):** The inclusion of `KROW University` and `Leaderboards` is a deliberate design choice to drive worker engagement and retention.
*   **Offline-First Capabilities (Planned):** The architecture supports local data caching, which is critical for workers who may have spotty data connections while on job sites.

## 9. Overview Diagram

```mermaid
flowchart TD
    subgraph StaffMobileApp["Staff Mobile Application"]
        direction TB
        subgraph PresentationLayer["Presentation Layer (UI)"]
            direction TB
            Router["Flutter Modular Navigation"]
            subgraph FeatureModules["Feature Modules"]
                AuthUI["Auth & Onboarding"]
                MarketUI["Marketplace & Jobs"]
                ShiftUI["Shift Management"]
                FinanceUI["Financial & Benefits"]
                ProfileUI["Profile & Compliance"]
            end
            Router --> FeatureModules
        end
        
        subgraph LogicLayer["Application Logic (State)"]
            direction TB
            Providers["Riverpod Providers"]
            AuthState["Auth State"]
            LocState["Geolocation State"]
            ShiftState["Shift State"]
        end
        
        subgraph DataLayer["Data & Service Layer"]
            direction TB
            MockService["Mock Data Service"]
            Repos["Repositories"]
        end
        
        PresentationLayer --> LogicLayer
        Providers --> AuthState
        Providers --> LocState
        Providers --> ShiftState
        LogicLayer --> DataLayer
    end
    
    subgraph ExternalServices["External Services"]
        direction TB
        Firebase["Firebase Backend"]
        Identity["Identity/SMS Service"]
        Maps["Google Maps/Geolocation"]
        Banking["Payment Processor"]
        DocVerify["Doc Verification"]
    end
    
    DataLayer --> ExternalServices
    
    %% Specific Data Flows
    AuthUI -- "Verify OTP" --> Identity
    MarketUI -- "Find Jobs" --> Repos
    ShiftUI -- "Clock In" --> Maps
    FinanceUI -- "Get Paid" --> Banking
    ProfileUI -- "Upload Docs" --> DocVerify
    Repos -- "Sync Data" --> Firebase
    
    classDef layer fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
    classDef module fill:#fff9c4,stroke:#fbc02d,stroke-width:1px,color:#000
    classDef system fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
    
    class PresentationLayer,LogicLayer,DataLayer layer
    class AuthUI,MarketUI,ShiftUI,FinanceUI,ProfileUI module
    class ExternalServices system
```