Krow-workspace/docs/ARCHITECTURE/client-mobile-application/use-case.md

# Client Application: Use Case Overview

This document details the primary business actions and user flows within the **Client Mobile Application**. It is organized according to the application's logical structure and navigation flow.

---

## 1. Application Access & Authentication

### 1.1 Initial Startup & Auth Check
*   **Actor:** Business Manager
*   **Description:** The system determines if the user is already logged in or needs to authenticate.
*   **Main Flow:**
    1. User opens the application.
    2. System checks for a valid session.
    3. If authenticated, user is directed to the **Home Dashboard**.
    4. If unauthenticated, user is directed to the **Get Started** screen.

### 1.2 Register Business Account (Sign Up)
*   **Actor:** New Business Manager
*   **Description:** Creating a new identity for the business on the Krow platform.
*   **Main Flow:**
    1. User taps "Sign Up".
    2. User enters company details (Name, Industry).
    3. User enters contact information and password.
    4. User confirms registration and is directed to the Main App.

### 1.3 Business Sign In
*   **Actor:** Existing Business Manager
*   **Description:** Accessing an existing account.
*   **Main Flow:**
    1. User enters registered email and password.
    2. System validates credentials.
    3. User is granted access to the dashboard.

---

## 2. Order Management (Requesting Staff)

### 2.1 Rapid Order (Urgent Needs)
*   **Actor:** Business Manager
*   **Description:** Posting a shift for immediate, same-day fulfillment.
*   **Main Flow:** Taps "RAPID" -> Selects Role -> Sets Quantity -> Confirms ASAP status -> Posts Order.

### 2.2 Scheduled Orders (Planned Needs)
*   **Actor:** Business Manager
*   **Description:** Planning for future staffing requirements.
*   **Main Flow:**
    1. User selects "Create Order".
    2. User chooses the frequency:
        *   **One-Time:** A single specific shift.
        *   **Recurring:** Shifts that repeat on a schedule (e.g., every Monday).
        *   **Permanent:** Long-term staffing placement.
    3. User enters date, time, role, and location.
    4. User reviews cost and posts the order.

---

## 3. Operations & Workforce Management

### 3.1 Monitor Today's Coverage (Coverage Tab)
*   **Actor:** Business Manager
*   **Description:** A bird's-eye view of all shifts happening today.
*   **Main Flow:** User navigates to "Coverage" tab -> Views percentage filled -> Identifies open gaps -> Re-posts unfilled shifts if necessary.

### 3.2 Live Activity Tracking
*   **Actor:** Business Manager
*   **Description:** Real-time feed of worker clock-ins and status updates.
*   **Location:** Home Tab / Coverage Detail.
*   **Main Flow:** User monitors the live feed for worker arrivals and on-site status.

### 3.3 Verify Worker Attire
*   **Actor:** Business Manager / Site Supervisor
*   **Description:** Ensuring staff arriving on-site meet the required dress code.
*   **Main Flow:** User selects an active shift -> Selects worker -> Checks attire compliance (shoes, uniform, ID) -> Submits verification.

### 3.4 Review & Approve Timesheets
*   **Actor:** Business Manager
*   **Description:** Finalizing hours worked for payroll processing.
*   **Main Flow:** User navigates to "Timesheets" -> Reviews actual vs. scheduled hours -> Taps "Approve" or "Dispute".

---

## 4. Reports & Analytics

### 4.1 Business Intelligence Reporting
*   **Actor:** Business Manager / Executive
*   **Description:** Accessing data visualizations to optimize business operations.
*   **Available Reports:**
    *   **Daily Ops:** Day-to-day fulfillment and performance.
    *   **Spend Report:** Financial breakdown of labor costs.
    *   **Forecast:** Projected staffing needs and costs.
    *   **Performance:** Worker and vendor reliability scores.
    *   **No-Show:** Tracking attendance issues.
    *   **Coverage:** Detailed fill-rate analysis.

---

## 5. Billing & Administration

### 5.1 Financial Management (Billing Tab)
*   **Actor:** Business Manager / Finance Admin
*   **Description:** Reviewing invoices and managing payment methods.
*   **Main Flow:** User navigates to "Billing" -> Views current balance -> Downloads past invoices -> Updates credit card/ACH info.

### 5.2 Manage Business Locations (Hubs)
*   **Actor:** Business Manager
*   **Description:** Defining different venues or branches where staff will be sent.
*   **Main Flow:** User goes to Settings -> Client Hubs -> Adds/Edits location details and addresses.

### 5.3 Profile & Settings Management
*   **Actor:** Business Manager
*   **Description:** Updating personal contact info and notification preferences.
*   **Main Flow:** User goes to Settings -> Edits Profile -> Toggles notification settings for shift updates and billing alerts.

---

# Use Case Diagram
```mermaid
flowchart TD
    subgraph AppInitialization [App Initialization]
        Start[Start App] --> CheckAuth{Check Auth Status}
        CheckAuth -- Authenticated --> GoHome[Go to Main App]
        CheckAuth -- Unauthenticated --> GetStarted[Go to Get Started]
    end

    subgraph Authentication [Authentication]
        GetStarted --> AuthChoice{Select Option}
        AuthChoice -- Sign In --> SignIn[Sign In Screen]
        AuthChoice -- Sign Up --> SignUp[Sign Up Screen]
        
        SignIn --> EnterCreds[Enter Credentials]
        EnterCreds --> VerifySignIn{Verify}
        VerifySignIn -- Success --> GoHome
        VerifySignIn -- Failure --> SignInError[Show Error]
        
        SignUp --> EnterBusinessDetails[Enter Business Details]
        EnterBusinessDetails --> CreateAccount[Create Account]
        CreateAccount -- Success --> GoHome
    end

    subgraph MainApp [Main Application Shell]
        GoHome --> Shell[Scaffold with Nav Bar]
        Shell --> TabNav{Tab Navigation}
        
        TabNav -- Index 0 --> Coverage[Coverage Tab]
        TabNav -- Index 1 --> Billing[Billing Tab]
        TabNav -- Index 2 --> Home[Home Tab]
        TabNav -- Index 3 --> Orders[Orders/Shifts Tab]
        TabNav -- Index 4 --> Reports[Reports Tab]
    end

    subgraph HomeActions [Home Tab Actions]
        Home --> CreateOrderAction{Create Order}
        CreateOrderAction -- Rapid --> RapidOrder[Rapid Order Flow]
        CreateOrderAction -- One-Time --> OneTimeOrder[One-Time Order Flow]
        CreateOrderAction -- Recurring --> RecurringOrder[Recurring Order Flow]
        CreateOrderAction -- Permanent --> PermanentOrder[Permanent Order Flow]
        
        Home --> QuickActions[Quick Actions Widget]
        Home --> Settings[Go to Settings]
        Home --> Hubs[Go to Client Hubs]
    end

    subgraph OrderManagement [Order Management Flows]
        RapidOrder --> SubmitRapid[Submit Rapid Order]
        OneTimeOrder --> SubmitOneTime[Submit One-Time Order]
        RecurringOrder --> SubmitRecurring[Submit Recurring Order]
        PermanentOrder --> SubmitPermanent[Submit Permanent Order]
        
        SubmitRapid --> OrderSuccess[Order Success]
        SubmitOneTime --> OrderSuccess
        SubmitRecurring --> OrderSuccess
        SubmitPermanent --> OrderSuccess
        OrderSuccess --> Home
    end

    subgraph ReportsAnalysis [Reports & Analytics]
        Reports --> SelectReport{Select Report}
        SelectReport -- Daily Ops --> DailyOps[Daily Ops Report]
        SelectReport -- Spend --> SpendReport[Spend Report]
        SelectReport -- Forecast --> ForecastReport[Forecast Report]
        SelectReport -- Performance --> PerfReport[Performance Report]
        SelectReport -- No-Show --> NoShowReport[No-Show Report]
        SelectReport -- Coverage --> CovReport[Coverage Report]
    end

    subgraph WorkforceMgmt [Workforce Management]
        Orders --> ViewShifts[View Shifts List]
        ViewShifts --> ShiftDetail[View Shift Detail]
        ShiftDetail --> VerifyAttire[Verify Attire]
        
        Home --> ViewWorkers[View Workers List]
        Home --> ViewTimesheets[View Timesheets]
        ViewTimesheets --> ApproveTime[Approve Hours]
        ViewTimesheets --> DisputeTime[Dispute Hours]
    end

    subgraph SettingsFlow [Settings & Configuration]
        Settings --> EditProfile[Edit Profile]
        Settings --> ManageHubsLink[Manage Hubs]
        Hubs --> AddHub[Add New Hub]
        Hubs --> EditHub[Edit Existing Hub]
    end

    %% Relationships across subgraphs
    OrderSuccess -.-> Coverage
    VerifySignIn -.-> Shell
    CreateAccount -.-> Shell
```