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

Staff Application: Use Case Overview

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

---

1. Application Access & Authentication

1.1 App Initialization

• Actor: Temporary Worker
• Description: The system checks if the user is logged in upon startup.
• Main Flow:
  1. Worker opens the app.
  2. System checks for a valid auth token.
  3. If valid, worker goes to Home.
  4. If invalid, worker goes to Get Started.

1.2 Onboarding & Registration

• Actor: New Worker
• Description: Creating a new profile to join the Krow network.
• Main Flow:
  1. Worker enters phone number.
  2. System sends SMS OTP.
  3. Worker verifies OTP.
  4. System checks if profile exists.
  5. If new, worker completes Profile Setup Wizard (Personal Info -> Role/Experience -> Attire Sizes).
  6. Worker enters the Main App.

---

2. Job Discovery (Home Tab)

2.1 Browse & Filter Jobs

• Actor: Temporary Worker
• Description: Finding suitable work opportunities.
• Main Flow:
  1. Worker taps "View Available Jobs".
  2. Worker filters by Role (e.g., Server) or Distance.
  3. Worker selects a job card to view details (Pay, Location, Requirements).

2.2 Claim Open Shift

• Actor: Temporary Worker
• Description: Committing to work a specific shift.
• Main Flow:
  1. From Job Details, worker taps "Claim Shift".
  2. System validates eligibility (Certificates, Conflicts).
  3. If eligible, shift is added to "My Schedule".
  4. If missing requirements, system prompts to Upload Compliance Docs.

2.3 Set Availability

• Actor: Temporary Worker
• Description: Defining working hours to get better job matches.
• Main Flow: Worker taps "Set Availability" -> Selects dates/times -> Saves preferences.

---

3. Shift Execution (Shifts & Clock In Tabs)

3.1 View Schedule

• Actor: Temporary Worker
• Description: Reviewing upcoming commitments.
• Main Flow: Navigate to "My Shifts" tab -> View list of claimed shifts.

3.2 GPS-Verified Clock In

• Actor: Temporary Worker
• Description: Starting a shift once on-site.
• Main Flow:
  1. Navigate to "Clock In" tab.
  2. System checks GPS location against job site coordinates.
  3. If On Site, "Swipe to Clock In" becomes active.
  4. Worker swipes to start the timer.
  5. If Off Site, system displays an error message.

3.3 Submit Timesheet

• Actor: Temporary Worker
• Description: Completing a shift and submitting hours for payment.
• Main Flow:
  1. Worker swipes to "Clock Out".
  2. Worker confirms total hours and break times.
  3. Worker submits timesheet for client approval.

---

4. Financial Management (Payments Tab)

4.1 Track Earnings

• Actor: Temporary Worker
• Description: Monitoring financial progress.
• Main Flow: Navigate to "Payments" -> View "Pending Pay" (unpaid) and "Total Earned" (paid).

4.2 Request Early Pay

• Actor: Temporary Worker
• Description: Accessing wages before the standard payday.
• Main Flow:
  1. Tap "Request Early Pay".
  2. Select amount to withdraw from available balance.
  3. Confirm transfer fee.
  4. Funds are transferred to the linked bank account.

---

5. Profile & Compliance (Profile Tab)

5.1 Manage Compliance Documents

• Actor: Temporary Worker
• Description: Keeping certifications up to date.
• Main Flow: Navigate to "Compliance Menu" -> "Upload Certificates" -> Take photo of ID/License -> Submit.

5.2 Manage Tax Forms

• Actor: Temporary Worker
• Description: Submitting legal employment forms.
• Main Flow: Navigate to "Tax Forms" -> Complete W-4 or I-9 digitally -> Sign and Submit.

5.3 Krow University Training

• Actor: Temporary Worker
• Description: Improving skills to unlock better jobs.
• Main Flow: Navigate to "Krow University" -> Select Module -> Watch Video/Take Quiz -> Earn Badge.

5.4 Account Settings

• Actor: Temporary Worker
• Description: Managing personal data.
• Main Flow: Update Bank Details, View Benefits, or Access Support/FAQs.

---

Use Cases Diagram

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 [Onboarding & Authentication]
        GetStarted --> InputPhone[Enter Phone Number]
        InputPhone --> VerifyOTP[Verify SMS Code]
        VerifyOTP --> CheckProfile{Profile Complete?}
        CheckProfile -- Yes --> GoHome
        CheckProfile -- No --> SetupProfile[Profile Setup Wizard]
        
        SetupProfile --> Step1[Personal Info]
        Step1 --> Step2[Role & Experience]
        Step2 --> Step3[Attire Sizes]
        Step3 --> GoHome
    end

    subgraph MainApp [Main Application Shell]
        GoHome --> Shell[Scaffold with Nav Bar]
        Shell --> TabNav{Tab Navigation}
        
        TabNav -- Index 0 --> Shifts[My Shifts Tab]
        TabNav -- Index 1 --> Payments[Payments Tab]
        TabNav -- Index 2 --> Home[Home Tab]
        TabNav -- Index 3 --> ClockIn[Clock In Tab]
        TabNav -- Index 4 --> Profile[Profile Tab]
    end

    subgraph HomeAndDiscovery [Job Discovery]
        Home --> ViewOpenJobs[View Available Jobs]
        ViewOpenJobs --> FilterJobs[Filter by Role/Distance]
        ViewOpenJobs --> JobDetail[View Job Details]
        JobDetail --> ClaimShift{Claim Shift}
        ClaimShift -- Success --> ShiftSuccess[Shift Added to Schedule]
        ClaimShift -- "Missing Req" --> PromptUpload[Prompt Compliance Upload]
        
        Home --> SetAvailability[Set Availability]
        Home --> ViewUpcoming[View Upcoming Shifts]
    end

    subgraph ShiftExecution [Shift Execution]
        Shifts --> ViewSchedule[View My Schedule]
        ClockIn --> CheckLocation{Verify GPS Location}
        CheckLocation -- "On Site" --> SwipeIn[Swipe to Clock In]
        CheckLocation -- "Off Site" --> LocationError[Show Location Error]
        
        SwipeIn --> ActiveShift[Shift In Progress]
        ActiveShift --> SwipeOut[Swipe to Clock Out]
        SwipeOut --> ConfirmHours[Confirm Hours & Breaks]
        ConfirmHours --> SubmitTimesheet[Submit Timesheet]
    end

    subgraph Financials [Earnings & Payments]
        Payments --> ViewEarnings[View Pending Earnings]
        Payments --> ViewHistory[View Payment History]
        ViewEarnings --> EarlyPay{Request Early Pay?}
        EarlyPay -- Yes --> SelectAmount[Select Amount]
        SelectAmount --> ConfirmTransfer[Confirm Transfer]
    end

    subgraph ProfileAndCompliance [Profile & Compliance]
        Profile --> ComplianceMenu[Compliance Menu]
        ComplianceMenu --> UploadDocs[Upload Certificates]
        ComplianceMenu --> TaxForms["Manage Tax Forms (W-4/I-9)"]
        
        Profile --> KrowUniversity[Krow University]
        KrowUniversity --> StartTraining[Start Training Module]
        
        Profile --> BankAccount[Manage Bank Details]
        Profile --> Benefits[View Benefits]
        Profile --> Support["Access Support/FAQs"]
    end

    %% Relationships across subgraphs
    SubmitTimesheet -.-> ViewEarnings
    PromptUpload -.-> ComplianceMenu
    ShiftSuccess -.-> ViewSchedule