Krow-workspace/docs/DESIGN/product-specification.md

# KROW Workforce Management Platform
## Product Specification for Designers

---

## Document Information

**Version**: 1.0  
**Last Updated**: March 14, 2026  
**Purpose**: This document describes the functional behavior and user experience of KROW's mobile workforce management platform from a design perspective.

---

## Table of Contents

1. [Introduction](#introduction)
2. [Platform Overview](#platform-overview)
3. [Client Application](#client-application)
   - [Authentication](#client-authentication)
   - [Home Dashboard](#client-home-dashboard)
   - [Billing](#client-billing)
   - [Coverage](#client-coverage)
   - [Hubs](#client-hubs)
   - [Orders](#client-orders)
   - [Reports](#client-reports)
   - [Settings](#client-settings)
4. [Staff Application](#staff-application)
   - [Authentication](#staff-authentication)
   - [Home Dashboard](#staff-home-dashboard)
   - [Clock In/Out](#staff-clock-in-out)
   - [Shifts](#staff-shifts)
   - [Availability](#staff-availability)
   - [Payments](#staff-payments)
   - [Profile](#staff-profile)
   - [Profile Sections](#staff-profile-sections)
5. [Glossary](#glossary)

---

## Introduction

### Purpose

This document provides a comprehensive overview of the KROW Workforce Management Platform's mobile applications. It is designed specifically for **designers** who need to understand, redesign, or create new user experiences without needing to read code.

### Scope

This document covers:
- **Two mobile applications**: Client (Business) app and Staff (Worker) app
- **All features**: Complete functionality across both apps
- **User flows**: How users navigate and interact with the system
- **User stories**: What users can do and why they would do it
- **Inputs and outputs**: What data users provide and what they receive

This document does **NOT** cover:
- Technical implementation details
- Backend systems or APIs
- Code architecture
- Performance specifications

### How to Use This Document

- Each feature is broken down into **user stories** following the format:
  - **As a** [type of user]
  - **I want to** [perform an action]
  - **So that** [I achieve a goal]

- Complex flows include **Mermaid diagrams** for visual clarity
- **Inputs** describe what users need to provide
- **Outputs** describe what users see or receive
- **Edge cases** highlight special scenarios or error conditions

### Document Conventions

- **Client** = Business users who hire staff
- **Staff** = Workers who accept shifts and perform jobs
- **Hub** = A business location/venue where work is performed
- **Shift** = A scheduled work period with specific start/end times
- **Order** = A staffing request placed by a client
- **Coverage** = The fulfillment status of shifts for a given day

---

## Platform Overview

### What is KROW?

KROW is a **workforce management platform** that connects businesses (clients) with workers (staff) for flexible staffing needs. The platform consists of two mobile applications:

1. **Client Application** - Used by businesses to:
   - Request staffing for their locations
   - Manage multiple business locations (hubs)
   - Track worker attendance and performance
   - Review and approve invoices
   - Monitor business metrics and reports

2. **Staff Application** - Used by workers to:
   - Find and accept available shifts
   - Set their weekly availability
   - Check in and out of shifts with location verification
   - Track earnings and request early payments
   - Complete onboarding and compliance requirements

### Key Concepts

- **Hub**: A physical business location where staff work (e.g., a restaurant, warehouse, or event venue)
- **Shift**: A scheduled work period with a specific role, start time, end time, and location
- **Order**: A staffing request created by a client specifying positions needed, dates, times, and location
- **Position**: A role within a shift (e.g., Server, Cook, Warehouse Associate)
- **Coverage**: The percentage or count of filled vs. unfilled positions for a given time period
- **Invoice**: A bill generated based on completed shifts, showing worker hours and total cost
- **Reliability Score**: A metric showing how dependable a staff member is (based on attendance, punctuality, cancellations)

---

# Client Application

The Client Application is designed for **business owners and managers** who need to staff their locations, track worker performance, and manage operational costs.

---

## Client: Authentication

### Purpose
Allow business users to create accounts, sign in, and manage their authentication sessions.

### User Stories

#### Story 1: Create Business Account
**As a** business owner  
**I want to** create a new KROW account with my company information  
**So that** I can start requesting staff for my business locations

**Task Flow:**
1. User initiates account creation process
2. User provides required business information:
   - Company name
   - Email address (for login and communications)
   - Password (meeting security requirements)
   - Password confirmation (to prevent typos)
3. System validates all provided information
4. System creates business account
5. User gains authenticated access to the platform

**Information Required:**
- Company name (text, required)
- Business email address (email format, must be unique)
- Secure password (minimum length, complexity requirements)
- Password confirmation (must match)

**Information Provided to User:**
- Account creation success confirmation
- Validation errors if any (e.g., "Email already in use", "Password too weak", "Passwords don't match")
- Access to authenticated features

**Edge Cases:**
- Duplicate email: System prevents creation with clear error message
- Network interruption: System provides retry mechanism
- Invalid data format: Real-time validation feedback during input
- Incomplete information: Clear indication of what's missing

---

#### Story 2: Sign In with Email
**As a** returning business user  
**I want to** authenticate using my registered email and password  
**So that** I can access my business data and features

**Task Flow:**
1. User initiates authentication process
2. User provides credentials:
   - Registered email address
   - Account password
3. System validates credentials against stored records
4. System grants authenticated access upon successful validation

**Information Required:**
- Email address (must match registered account)
- Password (must match stored credential)

**Information Provided to User:**
- Authentication success confirmation
- Access to authenticated features
- Clear error messaging if credentials invalid ("Invalid credentials")

**Edge Cases:**
- Forgotten password: System provides credential recovery mechanism (not yet implemented)
- Multiple failed attempts: Temporary access restriction may be triggered for account protection
- Network interruption: Retry capability provided

---

#### Story 3: Sign In with Social Authentication
**As a** business user  
**I want to** authenticate using my existing Google or Apple account  
**So that** I can access the platform quickly without managing separate passwords

**Task Flow:**
1. User selects social authentication provider (Google or Apple)
2. System initiates OAuth flow with selected provider
3. User authorizes KROW to access their account through provider interface
4. System receives authorization token from provider
5. System establishes authenticated session
6. User gains access to platform features

**Information Required:**
- Social provider choice (Google or Apple)
- Authorization approval through provider's authentication system

**Information Provided to User:**
- Authentication success confirmation
- Access to authenticated features
- Error message if authorization fails with retry option

**Edge Cases:**
- User cancels authorization: Process terminated, user can retry or use alternative method
- Account doesn't exist: System may create new account automatically or indicate linking requirement
- Authorization server unavailable: Clear error message with alternative authentication options

---

## Client: Home Dashboard

### Purpose
Provide clients with a customizable dashboard showing key business metrics, quick action shortcuts, and important notifications. Users can personalize widget visibility and order.

### User Stories

#### Story 1: View Business Dashboard
**As a** client  
**I want to** access a comprehensive overview of my key business metrics and pending tasks  
**So that** I can quickly understand my business status and identify actions needed

**Task Flow:**
1. User accesses primary business overview (default view after authentication)
2. System presents summary information modules displaying:
   - Current day's coverage status
   - Spending Insights : Weekly cost overview and projections
   - Upcoming scheduled shifts
   - Past orders with reorder capability
3. User can access detailed information for any metric area

**Information Required:**
- None (view-only access to business data)

**Information Provided to User:**
- Spending Insights : Weekly cost overview and projections
- Today's staff coverage status
- Past orders with reorder capability
- Upcoming shift schedule summary

**Edge Cases:**
- No data available: Empty states with guidance prompts ("No pending invoices", "Create your first order")
- Data loading: Progressive display of information as it becomes available
- Partial data failure: Available information shown with indication of what couldn't be loaded

---

#### Story 2: Customize Dashboard Layout
**As a** client  
**I want to** personalize which business metrics are visible and their priority order  
**So that** I can focus on information most relevant to my operational needs

**Task Flow:**
1. User initiates dashboard customization mode
2. System enables customization capabilities:
   - Metric modules become repositionable
   - Visibility controls become available for each module
3. User adjusts module positions to reflect preferred priority
4. User toggles visibility for individual metrics
5. User saves customization preferences
6. System persists user preferences
7. Dashboard reflects updated layout and visible metrics

**Information Required:**
- Module position preferences (sequential ordering)
- Module visibility preferences (shown/hidden for each)

**Information Provided to User:**
- Feedback during customization process
- Immediate updates when toggling metrics
- Confirmation of saved preferences ("Layout saved")
- Personalized dashboard reflecting choices

**Edge Cases:**
- All metrics hidden: System displays guidance to enable at least one metric
- Reset capability: Option to restore default configuration

---

#### Story 3: Reset Dashboard to Defaults
**As a** client  
**I want to** restore the dashboard to its original configuration  
**So that** I can undo my customizations if they're not meeting my needs

**Task Flow:**
1. User initiates dashboard customization mode
2. User requests restoration to default configuration
3. System requests confirmation of this action
4. User confirms restoration
5. System restores original metric order and visibility settings
6. User exits customization mode

**Information Required:**
- User confirmation (proceed or cancel restoration)

**Information Provided to User:**
- Confirmation prompt explaining what will be reset
- Success message ("Dashboard reset to default")
- Dashboard displaying default configuration

---

## Client: Billing

### Purpose
Manage invoices, review spending, and approve payments for completed shifts. Clients can track billing periods and drill down into invoice details.

### User Stories

#### Story 1: View Billing Summary
**As a** client  
**I want to** review my total staffing expenditure and invoice status for a selected time period  
**So that** I can understand and monitor my labor costs effectively

**Task Flow:**
1. User accesses billing information
2. User selects time period for analysis: Today | This Week | This Month | This Quarter (default: This Week)
3. System presents comprehensive spending data:
   - Total expenditure for selected period
   - Spending breakdown by category or location
   - Pending invoices requiring attention (count and total value)
   - Historical invoice records
4. User can access additional details for any displayed information

**Information Required:**
- Time period selection (predefined options)

**Information Provided to User:**
- Total spending amount for period (prominently displayed)
- Spending breakdown by category
- Pending invoices summary (quantity and total amount)
- Historical invoice list with key details

**Edge Cases:**
- No spending activity in period: Display $0 with explanatory message
- No pending invoices: Confirmation message that all invoices are processed
- Data loading: Progressive disclosure as information becomes available

---

#### Story 2: Review and Approve Pending Invoice
**As a** client  
**I want to** examine invoice details and approve or contest charges  
**So that** I can ensure payment accuracy for completed work

**Task Flow:**
1. User accesses pending invoices collection
2. User reviews list of all invoices awaiting approval
3. User selects specific invoice for detailed review
4. System presents comprehensive invoice information:
   - Worker identification
   - Work period (date and time range)
   - Hours worked (with break time calculations)
   - Compensation rate
   - Total calculated cost
   - Work location (hub)
5. User examines all details
6. User approves invoice or requests modifications
7. System processes decision and updates invoice status accordingly

**Information Required:**
- Invoice selection (from pending list)
- Approval decision (approve or request changes)
- If requesting changes: specific discrepancy details and notes

**Information Provided to User:**
- Complete invoice breakdown with all work details
- Worker performance notes if applicable
- Approval confirmation ("Invoice approved", moved to history)
- Change request form for documenting specific issues
- Error notification if processing fails (with retry capability)

**Edge Cases:**
- Disputed hours: Ability to flag time discrepancies with supporting notes
- Worker attendance issues: Relevant notes displayed on invoice (lateness, absence)
- Break time adjustments: Accurate reflection in calculated hours
- Processing failure: Retry mechanism with error explanation

---

#### Story 3: Review Invoice History
**As a** client  
**I want to** access my past approved invoices and payment records  
**So that** I can track historical spending and reference previous payments

**Task Flow:**
1. User accesses billing information
2. User navigates to historical invoice section
3. System presents past invoice records with:
   - Date of invoice
   - Total payment amount
   - Payment status (Paid)
   - Associated location(s)
4. User can select any invoice for comprehensive details
5. Historical invoice details include all original information plus payment confirmation date

**Information Required:**
- Invoice selection (from historical list)

**Information Provided to User:**
- chronological list of all processed invoices
- Full details of any selected historical invoice
- Payment confirmation information

**Edge Cases:**
- No payment history: Display message indicating no invoices have been processed yet
- Extensive history: Progressive loading mechanism for large volumes

---

## Client: Coverage

### Purpose
Provide real-time visibility into daily staffing levels, unfilled positions, and worker status. Clients can quickly identify coverage gaps and take action to fill them.

### User Stories

#### Story 1: View Daily Coverage Status
**As a** client  
**I want to** assess which shifts have assigned workers and which remain unfilled for a specific date  
**So that** I can identify staffing gaps and ensure adequate coverage

**Task Flow:**
1. User accesses staffing coverage information
2. System displays current day's coverage by default
3. User reviews comprehensive coverage data:
   - Selected date
   - Coverage statistics: total shifts, filled positions, unfilled positions, coverage percentage
   - Critical alerts if essential shifts lack staff
   - Complete shift inventory showing:
     - Worker assignment (name if filled, or unfilled status)
     - Work period (start and end times)
     - Required role or position
     - Work location
     - Current status (filled, unfilled, issue indicators like lateness)
4. User can examine all scheduled shifts

**Information Required:**
- None (defaults to current date)

**Information Provided to User:**
- Coverage metrics and percentages
- Status information for each shift
- Critical alerts for staffing gaps
- Complete shift details with assignment status

**Edge Cases:**
- No shifts scheduled: Message indicating no shifts exist for selected date
- Full coverage achieved: Celebration message for 100% staffing
- Worker delays: Status indicators showing "Running late" with appropriate urgency marking
- Data loading: Progressive display as information becomes available

---

#### Story 2: Select Different Date
**As a** client  
**I want to** view coverage information for any specific date  
**So that** I can plan ahead or review past staffing performance

**Task Flow:**
1. User initiates date selection process
2. System presents calendar date picker
3. User selects desired date (past, present, or future)
4. System retrieves and displays coverage data for selected date
5. Date indicator updates to reflect current selection

**Information Required:**
- Date selection (from calendar interface, any valid date)

**Information Provided to User:**
- Coverage data specific to selected date
- Updated statistics and shift inventory
- Date confirmation showing current selection

**Edge Cases:**
- Future date without scheduled shifts: Message indicating no shifts planned yet
- Past date: Historical data with final outcomes (completed, no-show, issues resolved)
- Current date: Real-time status information

---

#### Story 3: Re-post Unfilled Shift
**As a** client  
**I want to** broadcast available shifts to recruit additional workers  
**So that** I can fill last-minute staffing gaps quickly

**Task Flow:**
1. User reviews coverage showing unfilled positions
2. User identifies specific unfilled shift
3. User initiates re-posting action for that shift
4. System creates new recruitment notification to available workers
5. System confirms successful re-posting
6. Shift status updates to reflect active recruitment

**Information Required:**
- Shift selection (from unfilled positions)
- Re-post confirmation

**Information Provided to User:**
- Success confirmation ("Shift re-posted successfully")
- Updated shift status showing recruiting state
- Recruiting progress indicators

**Edge Cases:**
- Past shift time: Prevention of re-posting with explanation that shift time has elapsed
- Already recruiting: Indication that shift is already being actively recruited
- No eligible workers: Notification if no workers meet shift requirements

---

#### Story 4: Refresh Coverage Data
**As a** client  
**I want to** obtain the most current worker assignments and status information  
**So that** I can make decisions based on up-to-date staffing data

**Task Flow:**
1. User initiates data refresh
2. System displays loading state
3. System retrieves latest coverage information from server
4. Coverage information updates with current data
5. System displays timestamp of last update

**Information Required:**
- User-initiated refresh request

**Information Provided to User:**
- Loading state indicator
- Updated coverage information reflecting latest changes
- Timestamp showing when data was last refreshed

**Edge Cases:**
- No network connection: Error message with retry option
- Refresh already in progress: Prevention of duplicate requests
- No changes since last refresh: Confirmation that data is already current

---

## Client: Hubs

### Purpose
Manage business locations (hubs) where shifts take place. Clients can add, edit, view, and delete hub information.

### User Stories

#### Story 1: View All Hubs
**As a** client  
**I want to** access comprehensive information about all my business locations  
**So that** I can quickly review and manage my operational sites

**Task Flow:**
1. User accesses business locations management
2. System presents:
   - Summary information (guidance or total location count)
   - Capability to add new locations
   - Inventory of existing locations displaying:
     - Location name
     - Physical address
     - Key location details
3. User can browse all locations
4. User can access detailed information for any location

**Information Required:**
- None (view-only access to location data)

**Information Provided to User:**
- Complete list of business locations
- Location count summary (e.g., "You have 5 active hubs")
- Quick-access to key location details

**Edge Cases:**
- No locations registered: Empty state with guidance to add first location and prominent capability to do so

---

#### Story 2: Add New Hub
**As a** client  
**I want to** register a new business location in my account  
**So that** I can schedule staff shifts at that site

**Task Flow:**
1. User initiates new location creation
2. System presents location information form (creation mode)
3. User provides required location details:
   - Location name (text identifier)
   - Physical address (full address information, possibly multi-line)
   - Cost center assignment (selection from predefined options)
   - NFC tag identifier (optional for location verification)
4. User submits location information
5. System validates provided data and creates location record
6. System confirms successful creation
7. New location appears in complete locations inventory

**Information Required:**
- Location name (required text)
- Physical address (required text, may span multiple lines)
- Cost center assignment (required selection from predefined list)
- NFC tag identifier (optional text)

**Information Provided to User:**
- Creation success confirmation ("Hub created successfully")
- New location now available in inventory
- Return to locations overview

**Edge Cases:**
- Incomplete required information: Submission prevented with clear indication of missing fields
- Duplicate location name: Warning provided (but may be allowed)
- Network connectivity issues: Retry mechanism offered
- Invalid data format: Real-time validation feedback

---

#### Story 3: View Hub Details
**As a** client  
**I want to** access comprehensive information about a specific business location  
**So that** I can reference its address, cost center, and other operational details

**Task Flow:**
1. User selects specific location from inventory
2. System presents complete location information:
   - Location name
   - Full physical address
   - Cost center assignment
   - NFC tag identifier (if assigned)
   - Additional metadata (creation date, shift statistics, etc. if available)
3. User reviews information
4. User can initiate location modification
   OR request location removal
   OR return to locations inventory

**Information Required:**
- Location selection (from inventory)

**Information Provided to User:**
- Complete location details
- Capability to modify or remove location
- All associated metadata

---

#### Story 4: Edit Existing Hub
**As a** client  
**I want to** update information for an existing business location  
**So that** I can maintain accuracy when location details change

**Task Flow:**
1. User accesses location details
2. User initiates modification mode
3. System presents location information form (edit mode) with current values pre-populated
4. User modifies fields as needed:
   - Location name
   - Physical address
   - Cost center assignment
   - NFC tag identifier
5. User submits updated information
6. System validates and applies changes
7. System confirms successful update
8. Updated location information displayed

**Information Required:**
- Modified field values (same structure as location creation)
- Update confirmation

**Information Provided to User:**
- Update success confirmation ("Hub updated successfully")
- Refreshed location details reflecting changes
- Return to location details view

**Edge Cases:**
- Modification cancellation: Changes discarded, return to unmodified details
- No changes made: Notification that no modifications were detected
- Invalid data: Validation feedback before submission allowed
- Network issues: Retry mechanism with preserved changes

---

#### Story 5: Delete Hub
**As a** client  
**I want to** remove a business location from my account  
**So that** I can maintain a clean inventory of only active operational sites

**Task Flow:**
1. User accesses location details
2. User initiates deletion process
3. System requests deletion confirmation with warning about permanence
4. User confirms deletion intent
5. System removes location from account
6. System confirms successful deletion
7. Location no longer appears in inventory

**Information Required:**
- Deletion confirmation (proceed or cancel)
- Understanding of permanent action

**Information Provided to User:**
- Deletion confirmation (\"Hub deleted successfully\")
- Updated inventory without removed location
- Return to locations overview

**Edge Cases:**
- Location has active scheduled shifts: Additional warning about impact on shifts with confirmation
- Cancellation of deletion: Returns to details without removing location
- Location has historical data: Confirmation that historical records will be preserved even after location removal

---

## Client: Orders

### Purpose
Create staffing requests (orders) for business locations. Clients can specify positions needed, dates/times, and choose from multiple order types based on their staffing needs.

### Order Types Overview

- **One-Time**: Request staff for a single date (e.g., special event, busy day)
- **Recurring**: Request staff for specific days each week over a period (e.g., every Monday and Friday for 4 weeks)
- **Permanent**: Request staff for certain days indefinitely (e.g., every weekday ongoing)
- **Rapid**: Quick emergency staffing request (simplified flow)

### User Stories

#### Story 1: Choose Order Type
**As a** client  
**I want to** select the type of staffing order that matches my business need  
**So that** I can create an appropriate staffing request

**Task Flow:**
1. User initiates order creation process
2. System presents order type options with descriptions:
   - **One-Time Order** - "Need staff for a single day"
   - **Recurring Order** - "Need staff on specific days each week"
   - **Permanent Order** - "Need staff indefinitely for certain days"
   - **Rapid Order** - "Emergency staffing needed now"
3. User selects desired order type
4. System directs to appropriate order configuration process

**Information Required:**
- Order type selection (one of four available types)

**Information Provided to User:**
- Clear descriptions of each order type's purpose
- Access to selected order type's configuration process

---

#### Story 2: Create One-Time Order
**As a** client  
**I want to** request staff for a single day  
**So that** I can handle a special event or unusually busy day

```mermaid
graph TD
    A[Start: Select One-Time Order] --> B[Provide Event Name]
    B --> C[Select Vendor]
    C --> D[Select Date]
    D --> E[Select Hub Location]
    E --> F[Optional: Select Hub Manager]
    F --> G[Add First Position]
    G --> H{Add Another Position?}
    H -->|Yes| I[Add Position]
    I --> J[Specify Role<br/>Set Count<br/>Set Times<br/>Set Break]
    J --> H
    H -->|No| K[Review Order Summary]
    K --> L{Form Valid?}
    L -->|No| M[Review Validation Errors]
    M --> B
    L -->|Yes| N[Submit Order]
    N --> O[Success Confirmation]
    O --> P[View Order in Orders List]
```

**Task Flow:**
1. User selects One-Time Order type
2. User provides base order information:
   - **Event name**: Text description of the event (e.g., "Grand Opening")
   - **Vendor**: Selection from available vendors
   - **Date**: Calendar date selection
   - **Hub**: Selection from user's registered locations
   - System automatically retrieves available hub managers for selected location
   - **Hub manager**: Optional manager assignment
3. User defines required positions (can add multiple):
   - Initiate position addition
   - Specify for each position:
     - **Role**: Selection from available roles (e.g., Server, Cook, Bartender)
     - **Count**: Quantity of workers needed (numeric value)
     - **Start time**: Work period begin time
     - **End time**: Work period end time
     - **Lunch break**: Whether break is included (yes/no)
   - Confirm position addition
   - Position added to order
4. User can add additional positions by repeating position definition
5. User can remove positions from order as needed
6. User reviews complete order summary:
   - Event details (name, date, location)
   - All positions with timing details
   - Total workers required
7. User submits order for processing
8. System validates all information and creates staffing request
9. System confirms successful order placement
10. User can access order in orders list, filtered to show the order date

**Information Required:**
- Event name (text description)
- Vendor (selection from available options)
- Date (calendar date)
- Hub location (selection from user's registered locations)
- Hub manager (optional selection)
- For each position:
  - Role (selection from predefined roles)
  - Worker count (numeric, minimum 1)
  - Start time (time value)
  - End time (time value)
  - Break inclusion (boolean yes/no)

**Information Provided to User:**
- Order summary preview showing all details
- Validation feedback (which fields need attention)
- Success confirmation ("Order placed successfully")
- Access to view completed order

**Edge Cases:**
- No positions defined: Submission prevented until at least one position added
- End time precedes start time: Validation error for that position
- Past date selected: Warning or prevention based on business rules
- No hub managers available: Manager field remains optional or shows empty
- Network failure: Retry mechanism with order data preserved
- Validation errors: Clear indication of which fields require correction

---

#### Story 3: Create Recurring Order
**As a** client  
**I want to** request staff for specific days each week over a defined period  
**So that** I can handle predictable busy periods without creating multiple individual orders

**Task Flow:**
1. User selects Recurring Order type
2. User provides order information (similar structure to One-Time):
   - Event name
   - Vendor selection
   - **Start date**: First day to begin recurring schedule
   - **End date**: Final day of recurring schedule (maximum 29 days from start)
   - **Recurring days**: Which days of the week should repeat (Monday through Sunday)
   - Hub location
   - Hub manager (optional)
3. User defines required positions (same process as One-Time Order)
4. User reviews order summary displaying:
   - Selected recurring weekdays
   - Date range coverage
   - All position requirements
5. User submits order
6. System creates individual shift postings for each selected weekday within the date range

**Information Required:**
- Same as One-Time Order, plus:
  - Start date (calendar date)
  - End date (calendar date, maximum 29 days after start)
  - Day selections (Monday through Sunday)

**Information Provided to User:**
- Order summary showing complete recurrence pattern
- Success notification indicating quantity of shifts created
- Access to view all created orders

**Edge Cases:**
- No days selected: Submission prevented until at least one weekday chosen
- End date precedes start date: Validation error
- Date range exceeds 29 days: Error message with maximum limit explanation
- Single day selected: System processes as valid recurring pattern for that day

---

#### Story 4: Create Permanent Order
**As a** client  
**I want to** request staff for certain days indefinitely  
**So that** I can fill long-term positions without specifying an end date

**Task Flow:**
1. User selects Permanent Order type
2. User provides order information (similar to Recurring):
   - Event name
   - Vendor selection
   - **Start date**: When ongoing staffing begins (no end date required)
   - **Recurring days**: Which days of the week (Monday through Sunday)
   - Hub location
   - Hub manager (optional)
3. User defines required positions
4. User reviews order summary displaying:
   - "Permanent" or "Ongoing" status indicator
   - Start date
   - Selected recurring weekdays
   - All position requirements
5. User submits order
6. System creates ongoing shift postings without defined end date

**Information Required:**
- Same as Recurring Order, but only start date (no end date)
- Day selections (Monday through Sunday)

**Information Provided to User:**
- Order summary with "Permanent" status indication
- Success confirmation
- Access to view permanent order

**Edge Cases:**
- No days selected: Submission prevented until at least one weekday chosen
- Modifying or canceling permanent order: Requires separate management action (not covered in creation flow)

---

#### Story 5: Create Rapid Order
**As a** client  
**I want to** quickly request emergency staffing  
**So that** I can fill urgent last-minute needs efficiently

**Task Flow:**
1. User selects Rapid Order type
2. System presents simplified order creation process:
   - Possibly voice input capability or quick templates
   - Only essential fields required (location, role, count, timing)
3. User provides minimal required information
4. User submits immediate staffing request
5. System fast-tracks order with high priority to available workers

**Information Required:**
- Minimal essential fields (specific requirements TBD based on rapid_order implementation)
- Possibly voice description capability

**Information Provided to User:**
- Rapid confirmation of request received
- Immediate visibility of order to eligible workers

**Edge Cases:**
- Time-critical situations requiring fastest possible response
- Higher visibility or priority level to worker community
- Simplified validation for speed

---

#### Story 6: View All Orders
**As a** client  
**I want to** access a comprehensive list of all staffing orders I've created  
**So that** I can monitor their status and details

**Task Flow:**
1. User accesses orders management area
2. System presents orders in organized format (calendar or list structure)
3. User can filter by date range if desired
4. Order entries display key information:
   - Order date(s) or date range
   - Order type (One-Time, Recurring, Permanent)
   - Associated location(s)
   - Position count
   - Fill status (e.g., "5 of 10 positions filled")
5. User can access detailed information for any order

**Information Required:**
- Optional date range filter
- Refresh capability for updated information

**Information Provided to User:**
- Complete inventory of all orders
- Status indicators for each order
- Fill progress tracking

**Edge Cases:**
- No orders created yet: Guidance prompt to create first order
- Cancelled orders: Display with "Cancelled" status
- Very large order history: Progressive loading mechanism

---

## Client: Reports

### Purpose
Provide comprehensive business intelligence through various report types. Clients can track KPIs, analyze spending, monitor performance, and make data-driven decisions.

### User Stories

#### Story 1: View Reports Summary
**As a** client  
**I want to** access a high-level overview of key business metrics for a selected time period  
**So that** I can quickly understand my business performance

**Task Flow:**
1. User accesses business reports area
2. User views period options: Today | Week | Month | Quarter
3. User selects desired time period (default: Week)
4. System presents reports overview displaying:
   - Summary metric information (total orders, fill rate, total expenditure)
   - Access points for detailed report categories:
     - Daily Operations analysis
     - Performance metrics
     - Spend Analysis
     - Coverage analysis
     - Forecast projections
     - No-Show Tracking
5. User can access any detailed report category

**Information Required:**
- Period selection (predefined options)

**Information Provided to User:**
- Summary metrics for chosen period
- Access to all detailed report types

**Edge Cases:**
- No data for selected period: Message indicating no activity during timeframe

---

#### Story 2: View Performance Report (KPIs)
**As a** client  
**I want to** see my business performance KPIs with status context  
**So that** I can identify areas needing improvement

**Task Flow:**
1. User accesses Performance Report
2. User selects time period for analysis
3. System presents overview displaying:
   - **Overall Performance Score**: 0-100 with rating (Excellent ≥90, Good 75-89, Needs Work <75)
   - **4 Key Performance Indicators**:
     - **Fill Rate**: Percentage of positions filled (Target: 95%)
     - **Completion Rate**: Percentage of shifts completed without issues
     - **On-Time Rate**: Percentage of workers arriving on time
     - **Average Fill Time**: How quickly positions are filled (Target: 3 hours)
4. Each KPI shows current value, percentage, and comparison to target
5. User can change period to see trends over time

**Information Required:**
- Time period selection

**Information Provided to User:**
- Overall performance score with rating label
- Individual KPI values with percentage and target comparison
- Trend data when different periods are selected

**Edge Cases:**
- Insufficient data: Message indicating "Need more data to calculate"
- All KPIs meeting targets: Positive feedback message

---

#### Story 3: View Spend Report
**As a** client  
**I want to** analyze my staffing costs over time  
**So that** I can manage my budget and identify cost-optimization opportunities

**Task Flow:**
1. User accesses Spend Report from reports overview
2. User selects time period (week with Monday-Sunday view, or custom date range)
3. System presents financial analysis displaying:
   - **Total Spend**: Prominently displayed total expenditure for selected period
   - **Spending Breakdown** across multiple dimensions:
     - By business location
     - By role or position type
     - By day of week
   - Cost per hour metrics
4. User can drill into breakdown sections for additional detail

**Information Required:**
- Time period selection (week or custom date range)

**Information Provided to User:**
- Total expenditure amount
- Multi-dimensional spending breakdown
- Trend analysis over time

**Edge Cases:**
- No expenditure in period: Display $0 with explanatory message
- Significant spending anomalies: Highlighted with warning indicators

---

#### Story 4: View Daily Operations Report
**As a** client  
**I want to** access a comprehensive snapshot of operations for a specific date  
**So that** I can review that day's performance and activities

**Task Flow:**
1. User accesses Daily Operations report from reports overview
2. User selects specific date
3. System presents operational analysis displaying:
   - Orders created that day (count)
   - Positions filled (count and percentage)
   - Total staffing expenditure for the day
   - Worker attendance summary
   - Issues or incidents if any occurred
4. User reviews all operational metrics

**Information Required:**
- Date selection

**Information Provided to User:**
- Complete operational metrics for chosen date
- Summary information with counts and financial amounts
- Attendance and performance indicators

**Edge Cases:**
- Future date selected: Indication that data not yet available
- No activity on date: Message indicating no operations occurred
- Incomplete data: Clear indication of what information is still pending

---

#### Story 5: View Coverage Report
**As a** client  
**I want to** analyze my shift fill rates over time  
**So that** I can identify patterns and improve my staffing strategy

**Task Flow:**
1. User accesses Coverage Report from reports overview
2. User selects date range for analysis
3. System presents coverage analysis displaying:
   - Overall coverage percentage (e.g., 87% of shifts filled)
   - Unfilled positions count with alerts
   - Multi-dimensional breakdown:
     - By business location
     - By position type
     - By day of week
     - By time of day
   - Trend analysis showing coverage changes over time
4. User identifies patterns in low-coverage periods or locations

**Information Required:**
- Date range selection

**Information Provided to User:**
- Overall coverage percentage
- Detailed unfilled positions inventory
- Multi-dimensional breakdown analysis
- Trend analysis revealing patterns

**Edge Cases:**
- 100% coverage achieved: Success celebration message
- Chronic low coverage areas: Highlighted with improvement recommendations
- Insufficient data: Indication that broader date range would provide better analysis

---

#### Story 6: View Forecast Report
**As a** client  
**I want to** access predicted staffing demand and supply trends  
**So that** I can plan proactively and avoid staffing shortages

**Task Flow:**
1. User accesses Forecast Report from reports overview
2. System presents predictive analysis displaying:
   - Projected staffing demand for upcoming weeks
   - Available worker supply trend projections
   - Gap analysis comparing demand against supply
   - Strategic recommendations (e.g., "Consider posting shifts earlier to improve fill rates")
3. User reviews projections and trend analysis

**Information Required:**
- Optional date range for forecast period

**Information Provided to User:**
- Demand trend projections
- Supply trend projections
- Gap analysis identifying potential shortfalls
- Actionable recommendations for optimization

**Edge Cases:**
- New account with limited historical data: Message indicating forecast model is being developed
- Highly variable patterns: Wider confidence intervals shown
- Stable demand: High confidence projections with reinforcement

---

#### Story 7: View No-Show Report
**As a** client  
**I want to** track worker reliability and shift attendance issues  
**So that** I can address recurring problems and improve operational consistency

**Task Flow:**
1. User accesses No-Show Report from reports overview
2. User selects date range for analysis
3. System presents reliability analysis displaying:
   - Total no-show occurrences and rate (percentage of scheduled shifts)
   - Workers flagged for multiple no-show incidents
   - Shifts most frequently affected by no-shows
   - Breakdown by business location
4. User reviews data to identify reliability patterns

**Information Required:**
- Date range selection

**Information Provided to User:**
- No-show count and percentage rate
- Worker list with incident counts
- Location-based breakdown
- Recommendations for reliability improvement

**Edge Cases:**
- Perfect attendance record: Celebration message for zero no-shows
- High no-show rate: Alert highlighting the issue with suggested actions
- Repeated offenders: Clear identification for potential intervention

---

## Client: Settings

### Purpose
Manage user profile information, account preferences, and app settings. Clients can update their personal details and sign out.

### User Stories

#### Story 1: View Profile and Settings
**As a** client  
**I want to** access my profile information and account configuration options  
**So that** I can verify my details and access account management capabilities

**Task Flow:**
1. User accesses account settings area
2. System displays:
   - Profile information:
     - Profile picture or avatar
     - User name
     - Company name
   - Configuration options:
     - Profile editing capability
     - Preferences (if applicable)
     - Help and Support access (if applicable)
     - Sign out capability
3. User reviews information and available options

**Information Required:**
- None (view-only access to profile data)

**Information Provided to User:**
- Complete profile information display
- Available settings and configuration menu options

---

#### Story 2: Edit Profile Information
**As a** client  
**I want to** update my personal information  
**So that** my account details remain current and accurate

**Task Flow:**
1. User initiates profile editing process
2. System presents profile information form with current values:
   - Profile picture (with capability to change)
   - First name
   - Last name
   - Email address
   - Phone number
3. User modifies desired fields
4. User submits updated information
5. System validates and applies changes
6. System confirms successful update
7. User returns to settings view with updated information

**Information Required:**
- Profile picture (image file)
- First name (text)
- Last name (text)
- Email address (valid email format)
- Phone number (valid phone format)

**Information Provided to User:**
- Update success confirmation ("Profile updated successfully")
- Refreshed profile information in settings
- Return to settings overview

**Edge Cases:**
- Invalid email format: Validation error with format guidance
- Required fields empty: Submission prevented until complete
- Modification cancellation: Changes discarded, return to unmodified state
- Email already registered to another account: Error message indicating conflict
- Network issues: Retry mechanism with preserved changes

---

#### Story 3: Sign Out
**As a** client  
**I want to** terminate my authenticated session  
**So that** I can secure my account when not in use

**Task Flow:**
1. User initiates sign out process
2. System requests confirmation: "Are you sure you want to sign out?"
3. User confirms intent to sign out
4. System terminates authenticated session
5. User returned to authentication entry point

**Information Required:**
- Sign out confirmation (proceed or cancel)

**Information Provided to User:**
- Sign out confirmation
- Access to authentication entry point
- Session cleared confirmation

**Edge Cases:**
- Cancellation of sign out: Return to settings without terminating session
- Automatic timeout: Session termination after period of inactivity (if implemented)
- Unsaved changes elsewhere: Warning about potential data loss (if applicable)

---

# Staff Application

The Staff Application is designed for **workers** who want to find shifts, track their work, manage availability, and get paid.

---

## Staff: Authentication

### Purpose
Allow workers to sign up and sign in using phone number verification. This includes a multi-step profile setup wizard for new users.

### User Stories

#### Story 1: Sign Up with Phone Number
**As a** new worker  
**I want to** create an account using my phone number  
**So that** I can start finding work through KROW

```mermaid
graph TD
    A[Start: Open App] --> B[Begin Registration]
    B --> C[Choose Sign Up]
    C --> D[Provide Phone Number<br/>10-digit US format]
    D --> E{Phone Valid?}
    E -->|No| F[Validation Error]
    F --> D
    E -->|Yes| G[Request Verification Code]
    G --> H[31-second Cooldown Period]
    H --> I[Receive SMS with OTP]
    I --> J[Provide 6-digit OTP]
    J --> K{OTP Correct?}
    K -->|No| L[Verification Error<br/>Retry Available]
    L --> J
    K -->|Yes| M[Account Created]
    M --> N[Begin Profile Setup]
    N --> O[Step 1: Basic Info]
    O --> P[Step 2: Location Preferences]
    P --> Q[Step 3: Experience/Skills]
    Q --> R[Submit Profile]
    R --> S[Access Home Dashboard]
```

**Task Flow - Phone Verification:**
1. User opens application and initiates account creation process
2. User selects registration option
3. System presents phone verification process
4. User provides phone number:
   - 10 digits for US numbers
   - System automatically formats as input progresses (e.g., (555) 123-4567)
5. User requests verification code delivery
6. System sends SMS with 6-digit OTP
7. System initiates cooldown timer (31 seconds before resend capability)
8. User receives SMS and provides 6-digit OTP
9. System verifies OTP authenticity
10. Upon successful verification, system creates user account
11. User proceeds to Profile Setup wizard

**Information Required:**
- Phone number (10 digits, automatically formatted)
- OTP code (6 digits from SMS)

**Information Provided to User:**
- SMS delivery confirmation: "Code sent to (555) 123-4567"
- Cooldown timer: "Resend available in 31s"
- Successful verification: Proceed to Profile Setup
- Verification failure: "Invalid code. Please try again." with retry capability

**Edge Cases:**
- Invalid phone format: Immediate error message display
- OTP expiration: Capability to request new code
- Excessive failed attempts: Temporary account lock with "Try again in X minutes" message
- SMS not received: "Resend Code" capability available after cooldown period
- Network issues: Retry mechanism for code delivery

---

#### Story 2: Complete Profile Setup Wizard
**As a** new worker  
**I want to** complete my profile setup through guided steps  
**So that** clients can discover me and I can be matched to appropriate work opportunities

**Task Flow - 3-Step Wizard:**

**Step 1: Basic Information**
1. User sees progress indicator ("Step 1 of 3")
2. User provides full name (minimum 2 characters)
3. User proceeds to next step

**Step 2: Location Preferences**
1. User sees progress indicator ("Step 2 of 3")
2. System presents multi-select list of available work locations/areas
3. User selects preferred work locations (minimum one required)
4. User can return to previous step or proceed forward

**Step 3: Experience & Skills**
1. User sees progress indicator ("Step 3 of 3")
2. System presents multi-select list of roles/skills (e.g., Server, Cook, Warehouse)
3. User selects all applicable skills (minimum one required)
4. User can return to previous step or complete setup
5. User submits completed profile information
6. System validates all provided information
7. Upon validation success, user gains access to main application

**Information Required:**
- **Step 1**: Full name (text, minimum 2 characters)
- **Step 2**: Location preferences (multi-select, minimum 1 selection)
- **Step 3**: Skills and experience (multi-select, minimum 1 selection)

**Information Provided to User:**
- Progress indicators throughout wizard (1 of 3, 2 of 3, 3 of 3)
- Navigation controls (back, next, submit capabilities)
- Validation feedback for incomplete or invalid data
- Welcome confirmation: "Welcome to KROW!"
- Access to main application features

**Edge Cases:**
- Required fields incomplete: Forward progression prevented until requirements met
- Returning to authentication from Step 1: May result in progress loss (warning appropriate)
- Application closure during setup: Progress preserved for later completion
- Network interruption: Setup data preserved locally for retry

---

#### Story 3: Sign In with Phone Number
**As a** returning worker  
**I want to** authenticate using my phone number  
**So that** I can quickly access my account

**Task Flow:**
1. User initiates authentication process
2. System presents phone verification (same process as registration)
3. User provides phone number
4. User requests verification code
5. System sends OTP via SMS
6. User provides received OTP
7. System verifies OTP authenticity
8. Upon successful verification, user gains authenticated access
9. User accesses main application

**Information Required:**
- Phone number (10 digits)
- OTP code (6 digits from SMS)

**Information Provided to User:**
- SMS delivery confirmation
- Successful authentication: Access to main application
- Authentication failure: "Invalid code" with retry capability

**Edge Cases:**
- Unregistered phone number: Error message "No account found. Please sign up."
- Incomplete profile: Automatic redirect to Profile Setup wizard at last incomplete step
- All standard OTP edge cases (expiration, too many attempts, SMS delivery issues)

---

## Staff: Home Dashboard

### Purpose
Provide workers with a personalized dashboard showing shift summaries, recommendations, benefits overview, and quick actions.

### User Stories

#### Story 1: View Shift Summary
**As a** worker  
**I want to** access my upcoming shifts and discover recommended opportunities  
**So that** I can plan my schedule and find new work

**Task Flow:**
1. User accesses main application overview
2. System presents personalized information:
   - **Personal greeting**: "Hello, [Worker Name]"
   - **Today's Schedule**:
     - All shifts scheduled for current day
     - Each displaying: Time, location, role, current status
   - **Tomorrow's Schedule**:
     - Preview of next day's commitments
   - **Recommended Opportunities**:
     - Algorithm-suggested shifts based on preferences and work history
     - Capability to browse complete opportunity marketplace
   - **Benefits Summary**:
     - Quick overview of benefits information
     - Access to detailed benefits information
3. User can browse all information sections
4. User can access detailed information for any individual shift
5. User can access complete shift marketplace

**Information Required:**
- None (view-only access to dashboard data)

**Information Provided to User:**
- Personalized greeting
- Today's complete shift schedule
- Tomorrow's shift preview
- Algorithmically recommended shifts
- Benefits information summary
- Quick access to key features

**Edge Cases:**
- No shifts scheduled today: Message "No shifts scheduled today" with access to shift discovery
- Incomplete profile: System notification prompting profile completion to unlock shift recommendations and features
- No recommended shifts: Alternative messaging suggesting profile enhancement or shift marketplace browsing

---

#### Story 2: Enable Auto-Match for Shifts
**As a** worker  
**I want to** automatically receive shift matches based on my preferences  
**So that** I don't miss opportunities without constantly monitoring the application

**Task Flow:**
1. User sees auto-match capability toggle in application
2. User activates auto-match feature
3. System confirms activation: "Auto-match enabled. You'll be notified when shifts matching your preferences are available."
4. User receives push notifications when suitable shifts are identified
5. User can deactivate auto-match by toggling off

**Information Required:**
- Auto-match preference (enabled/disabled)

**Information Provided to User:**
- Activation confirmation message
- Push notifications when matching shifts are found
- Settings indicator showing auto-match status

**Edge Cases:**
- Incomplete profile: Auto-match unavailable with guidance "Complete your profile to enable auto-match"
- Push notifications disabled: Prompt to enable device notification permissions
- No matching shifts found: Suggestions to broaden preferences or check back later

---

#### Story 3: View Benefits Information
**As a** worker  
**I want to** learn about benefits available to me  
**So that** I understand the complete value proposition of working through KROW

**Task Flow:**
1. User accesses benefits information from overview
2. System presents comprehensive benefits overview displaying:
   - Complete list of available benefits (e.g., health insurance, early pay, performance bonuses)
   - Detailed description of each benefit
   - Eligibility requirements for each benefit
   - Instructions for accessing or enrolling in each benefit
3. User reviews all benefits information
4. User returns to main overview

**Information Required:**
- None (view-only access to benefits data)

**Information Provided to User:**
- Complete benefits inventory with descriptions
- Eligibility criteria for each benefit
- Enrollment or access instructions
- Current eligibility status if applicable

**Edge Cases:**
- Not yet qualified for benefits: Message indicating "Complete more shifts to unlock benefits" with progress tracking
- Partially eligible: Clear indication of which benefits are currently accessible
- Enrollment required: Call-to-action for benefits requiring active enrollment

---

## Staff: Clock In Out

### Purpose
Track worker attendance with time-window enforcement and location verification. Workers view their scheduled shifts, check in using a swipe or NFC gesture, record break details during check-out, and can override location requirements with a written justification when GPS is unavailable.

### User Stories

#### Story 1: View and Select Today's Shift
**As a** worker  
**I want to** see my scheduled shifts for today and select which one I'm attending  
**So that** I can clock in to the correct shift

**Task Flow:**
1. Worker accesses the attendance tracking area
2. System loads the worker's shifts for the selected date (defaults to today)
3. Worker can navigate through a date strip spanning 3 days in the past, today, and 3 days ahead; only today is interactive
4. Each shift in the list shows:
   - Role or position title
   - Client name and venue location
   - Scheduled start and end times
   - Hourly rate
5. If already clocked in, the active shift is automatically highlighted
6. Otherwise, the most recent shift in the list is selected by default
7. Worker selects a shift to begin time-window and location verification for that venue

**Information Required:**
- Shift selection (when multiple shifts are scheduled for the day)

**Information Provided to User:**
- All shifts scheduled for today
- Which dates in the strip have shifts scheduled
- Which shift is currently active or selected

**Edge Cases:**
- No shifts today: Message "No shifts scheduled today" with access to the shift marketplace
- Single shift: Auto-selected, no manual selection needed

---

#### Story 2: Check In to Shift
**As a** worker  
**I want to** register my arrival at a shift within the allowed time window  
**So that** my work time is tracked from the moment I arrive

```mermaid
graph TD
    A[Select Shift] --> B{Within Check-In Window?}
    B -->|Too Early| C[Notice: Shows Time When Check-In Opens]
    B -->|Window Open| D{GPS Permission?}
    D -->|Denied| E[Permission Denied — Override Available]
    D -->|Permanently Denied| F[Must Enable in Device Settings — Override Available]
    D -->|Granted| G{GPS Service Enabled?}
    G -->|Off| H[GPS Off — Override Available]
    G -->|On| I[Acquiring Location — 30s Window]
    I -->|Within 500m| J[Location Verified]
    I -->|Outside 500m| K[Outside Geofence — Override Available]
    I -->|Timeout| L[GPS Timeout — Retry or Override]
    E --> M{Override with Justification?}
    F --> M
    H --> M
    K --> M
    L --> M
    M -->|Submit Justification| J
    M -->|Retry GPS| I
    J --> N{Confirm Method?}
    N -->|Swipe| O[Complete Swipe Gesture]
    N -->|NFC| P[Complete NFC Tap]
    O --> Q[Check-In Submitted]
    P --> Q
    Q --> R[Check-In Confirmed — Background Location Tracking Begins]
```

**Task Flow:**
1. Worker selects a shift
2. System checks the current time against the shift's scheduled start time
3. If more than 15 minutes before shift start: check-in is not yet available; the time when it opens is displayed
4. Once within the check-in window, location verification begins automatically
5. System requests GPS permission if not already granted
6. GPS attempts to acquire the worker's current location (up to 30-second window)
7. System calculates distance from the shift's venue coordinates
8. If within 500 metres: check-in is enabled
9. If location cannot be verified (outside geofence, GPS timeout, permission issues): worker may provide a written justification to override — see Story 3
10. With location verified or overridden, worker confirms check-in using one of two methods:
    - **Swipe confirmation**: Drag a slider across at least 80% of its range
    - **NFC confirmation**: Tap device to the NFC reader at the venue
11. System submits check-in to the backend
12. System confirms check-in with a timestamp
13. Background location tracking begins automatically for the duration of the shift

**Information Required:**
- GPS permission (system request)
- Shift selection (if multiple shifts today)
- Check-in confirmation (swipe gesture or NFC tap)

**Information Provided to User:**
- Time window status: how long until check-in opens, or confirmation that it is open
- Location verification status and current distance from venue
- Check-in confirmation with exact timestamp
- Confirmation that background location tracking is now active

**Edge Cases:**
- **Too early to check in**: Check-in unavailable; exact time when it becomes available is shown
- **GPS permission denied**: Worker can open device settings or use justification override
- **GPS permanently denied**: Worker must enable location in device settings; override also available
- **GPS service off**: Worker directed to enable device GPS; override also available
- **Outside geofence**: Distance from venue displayed; override with written justification permitted
- **GPS timeout (30 seconds)**: Worker can retry location check or use justification override
- **Already checked in**: Check-out flow shown instead; prior check-in time displayed

---

#### Story 3: Override Location Requirement
**As a** worker  
**I want to** clock in even when location verification cannot be completed  
**So that** my attendance is recorded despite GPS issues beyond my control

**Task Flow:**
1. Location verification fails or cannot complete (permission denied, GPS off, outside 500m, or 30-second timeout)
2. System presents the reason for the location issue and an option to proceed without verification
3. Worker requests to proceed without location verification
4. System presents a written justification form
5. Worker provides a written explanation of why location verification is not possible
6. Justification must be non-empty before submission is allowed
7. Worker submits justification
8. System marks the attendance record as location-overridden and stores the justification note
9. Check-in confirmation (swipe or NFC) becomes available
10. Worker proceeds with normal check-in flow

**Information Required:**
- Written justification (required; cannot be empty)

**Information Provided to User:**
- Explanation of the location issue encountered
- Confirmation that the override justification has been recorded
- Confirmation that check-in can now proceed

**Edge Cases:**
- Empty justification: Submission is prevented until text is provided
- Justification is stored alongside the attendance record for administrative review

---

#### Story 4: Check Out with Break Details
**As a** worker  
**I want to** record my departure and any break taken during my shift  
**So that** my total worked hours and compensation are calculated accurately

**Task Flow:**
1. Worker has previously checked in and is within the check-out time window (within 15 minutes of shift end)
2. If attempting to check out too early: check-out is not yet available; the time when it opens is displayed
3. Same location verification and override rules apply as check-in (Story 2 and Story 3)
4. Worker confirms check-out using swipe or NFC (same methods as check-in)
5. System presents a multi-step break details form:
   - **Step 1**: Did you take a lunch break? (Yes / No)
   - **Step 2a — if Yes**: Select break start time and break end time (available in 15-minute increments)
   - **Step 2b — if No**: Select the reason no break was taken (from a predefined list)
   - **Step 3**: Optional additional notes about the shift
   - **Step 4**: Review summary of all submitted details
6. Worker confirms the summary
7. System submits check-out and break information to the backend
8. System confirms shift is complete
9. Background location tracking stops automatically

**Information Required:**
- Check-out confirmation (swipe gesture or NFC tap)
- Break taken: Yes or No
- If Yes: break start time and break end time (15-minute increments)
- If No: reason for no break (selection from predefined options)
- Optional: additional shift notes

**Information Provided to User:**
- Time window status (when check-out becomes available, or confirmed open)
- Break detail form with step-by-step guidance
- Summary of all submitted information before final confirmation
- Check-out confirmation with exact timestamp
- Shift completion status

**Edge Cases:**
- **Too early to check out**: Check-out unavailable; exact time when it becomes available is shown
- **Geofence and override rules**: Same location verification and override flow as check-in applies
- **Break time selection**: Times are chosen from 15-minute slot options, not free-text entry
- **Network issue**: Check-out request queued for submission when connection is restored

---

#### Story 5: Track Commute to Shift
**As a** worker  
**I want to** share my estimated arrival time before a shift  
**So that** the client knows when to expect me

**Task Flow:**
1. Before a shift begins, the system offers commute tracking
2. Worker consents to sharing commute location data
3. System monitors the worker's distance to the venue and calculates estimated time of arrival
4. ETA information is made visible to the client
5. Worker is shown their current distance to the venue and estimated arrival time
6. When the worker arrives within range of the venue, commute tracking automatically deactivates

**Information Required:**
- Consent to share commute location

**Information Provided to User:**
- Current distance to the shift venue
- Estimated arrival time (e.g., "Arriving in 12 minutes")
- Confirmation when commute tracking deactivates upon arrival

**Edge Cases:**
- Location permission required for commute tracking to function
- Worker can withdraw consent and disable commute tracking at any time
- Route changes cause estimated arrival time to automatically recalculate

---

## Staff: Shifts

### Purpose
Comprehensive shift management including browsing available shifts (marketplace), managing assigned shifts, and viewing shift history.

### User Stories

#### Story 1: View My Assigned Shifts
**As a** worker  
**I want to** access all shifts I'm assigned to  
**So that** I can plan my schedule and track my commitments

**Task Flow:**
1. User accesses shift management area
2. System displays "My Shifts" view by default
3. User reviews complete list of assigned/accepted shifts (chronologically sorted)
4. Each shift entry displays:
   - Date and day of week
   - Start and end times
   - Role or position
   - Location name and address
   - Compensation rate
   - Status (Upcoming, Confirmed, Pending)
5. User can browse all shifts
6. User can access detailed information for any shift
7. User can confirm attendance or cancel shift (if policy permits)

**Information Required:**
- None (view-only access to assigned shifts)

**Information Provided to User:**
- Complete inventory of assigned shifts
- Shift status indicators
- Quick action capabilities (Confirm, Cancel if allowed)

**Edge Cases:**
- No assigned shifts: Message "No upcoming shifts. Browse available shifts in Find tab."
- Cancelled shifts: Display with "Cancelled" status
- Past shifts: May display with "View Feedback" or "View Details" capability
- Conflicting shifts: Warnings or conflict notifications

---

#### Story 2: Browse and Book Available Shifts
**As a** worker  
**I want to** browse available shifts in the marketplace and commit to ones that interest me  
**So that** I can fill my schedule and maximize earnings

```mermaid
graph TD
    A[Start: Access Find Shifts] --> B[Load Available Shifts]
    B --> C[Display Shift Inventory]
    C --> D{User Action?}
    D -->|Filter| E[Select Job Type Filter]
    E --> F[Apply Filter]
    F --> C
    D -->|Search| G[Provide Search Query<br/>Location or keyword]
    G --> H[Apply Search]
    H --> C
    D -->|View Shift| I[Select Shift]
    I --> J[Open Shift Details]
    J --> K[Verify Profile Status]
    K --> L{Profile Complete?}
    L -->|No| M[Profile Completion Required<br/>Complete profile to book shifts]
    M --> N[Access Profile Completion]
    L -->|Yes| O[Display Complete Shift Information<br/>Date, Time, Location<br/>Pay, Requirements]
    O --> P{User Decision?}
    P -->|Book| Q[Initiate Booking]
    Q --> R[Confirm Booking]
    R --> S[Submit Booking Request]
    S --> T[Success: Shift Assignment Confirmed]
    T --> U[View in My Shifts]
    P -->|Decline| V[Return to Marketplace]
    V --> C
```

**Task Flow:**
1. User accesses shift marketplace
2. System loads all available shifts matching user's preferences
3. User reviews shift inventory displaying:
   - Date and time period
   - Duration
   - Role or position
   - Location
   - Compensation rate (hourly or flat rate)
   - Distance from user's current location (if location enabled)
4. User can apply filters:
   - By job type (selection from available categories)
   - By search criteria (text input for location or keywords)
5. User selects specific shift for detailed review
6. System presents comprehensive shift information:
   - Complete date and time details
   - Venue name and complete address
   - Compensation breakdown
   - Required qualifications (skills needed)
   - Break schedule
   - Job description
   - **Profile completion requirement** (if incomplete)
7. If profile complete, booking capability enabled
8. User initiates booking process
9. System requests confirmation: "Confirm booking for [Shift Name] on [Date]?"
10. User confirms booking intent
11. System processes shift assignment
12. Success confirmation: "Shift booked successfully!"
13. Shift now appears in "My Shifts" area
14. User can access My Shifts or continue browsing

**Information Required:**
- Job type filter (selection from available options)
- Search query (text input)
- Shift selection
- Booking confirmation

**Information Provided to User:**
- Filtered or searched shift results
- Complete shift details
- Booking confirmation dialog
- Success confirmation
- Shift assignment in My Shifts area

**Edge Cases:**
- **Profile incomplete**: Booking disabled or hidden; message displayed: "Complete your profile to book shifts" with profile access link
- **Shift capacity reached**: Error message "This shift has been filled. Try another."
- **Schedule conflict**: Warning "You have another shift at this time. Booking will create a conflict."
- **No matching shifts**: Empty state with "No shifts match your criteria" and filter reset capability
- **Distance consideration**: Warning for distant shifts but booking still permitted
- **Network issues**: Queue booking request for submission when connected

---

#### Story 3: Decline Available Shift
**As a** worker  
**I want to** remove shifts I'm not interested in from my view  \n**So that** I can focus on opportunities that better match my preferences

**Task Flow:**
1. User reviews shift details
2. User indicates disinterest in specific shift\n3. System removes shift from user's feed or marks as declined
4. User returns to marketplace
5. Optional: System requests feedback \"Why did you decline?\"

**Information Required:**
- Decline action confirmation
- Optional: Decline reason feedback

**Information Provided to User:**
- Shift removed from current view
- Optional: Feedback collection interface

**Edge Cases:**
- Declined shift may reappear if search filters change
- Frequent declines: System may adjust recommendation algorithm\n- Undo capability: Brief window to reverse decline action if available
- Too many declines: System may adjust recommendations

---

#### Story 4: View Shift History
**As a** worker  
**I want to** access all my past completed shifts  
**So that** I can reference previous work and track my earnings history

**Task Flow:**
1. User accesses shift history area
2. System presents chronologically ordered list of completed shifts (most recent first)
3. Each shift entry displays:
   - Date
   - Role or position
   - Location name
   - Hours worked
   - Total compensation
   - Status (Completed, No-Show, Cancelled)
4. User can access detailed information for any shift
5. Historical shift details may include:
   - Arrival and departure timestamps
   - Break duration
   - Client feedback or rating (if available)
6. User can filter history by date range

**Information Required:**
- None (view-only access to historical data)
- Optional: Date range filter

**Information Provided to User:**
- Complete inventory of past shifts
- Total earnings over selected period
- Detailed information for individual shifts

**Edge Cases:**
- No history available: Message "No completed shifts yet" with encouragement
- Disputed shift: Status indicator showing "Under Review"
- Multiple pages: Progressive loading or pagination for extensive history

---

## Staff: Availability

### Purpose
Allow workers to set their weekly availability, indicating which days and times they are free to work. This helps the system match workers to appropriate shifts.

### User Stories

#### Story 1: Set Weekly Availability
**As a** worker  
**I want to** indicate which days of the week I'm available to work  
**So that** I only receive shift offers matching my schedule

**Task Flow:**
1. User accesses availability management
2. System displays current week (Monday-Sunday)
3. For each day, information presented:
   - Day name (e.g., "Monday")
   - Date
   - Availability status control (available/unavailable)
   - Optional: Specific time slot controls (if granular availability enabled)
4. User adjusts availability status for each day
5. System automatically saves changes (optimistic updates)
6. Brief confirmation: "Availability saved"

**Information Required:**
- Day availability status (7 day selections)
- Optional: Time slot availability within each day

**Information Provided to User:**
- Confirmation of status changes
- Automatic save confirmation
- Updated availability reflected in shift matching algorithm

**Edge Cases:**
- All days marked unavailable: Warning "No availability set. You won't receive shift offers."
- Changes during system loading: Queue changes for application after load completion
- Network issues: Local changes preserved and synchronized when connected

---

#### Story 2: Use Quick Availability Presets
**As a** worker  
**I want to** quickly apply common availability patterns  
**So that** I don't need to configure each day individually

**Task Flow:**
1. User sees quick preset options:
   - "All Week" - All 7 days available
   - "Weekdays Only" - Monday-Friday available
   - "Weekends Only" - Saturday-Sunday available
   - "Clear All" - All days unavailable
2. User selects desired preset
3. System applies pattern to all day availability settings
4. Changes automatically saved
5. User can manually adjust individual days after applying preset

**Information Required:**
- Preset selection

**Information Provided to User:**
- Availability settings updated to match preset
- Automatic save confirmation

**Edge Cases:**
- Current settings already match preset: Confirmation displayed even without changes
- Manual adjustments after preset: Overrides preset for specific days

---

#### Story 3: Set Availability for Future Weeks
**As a** worker  
**I want to** configure my availability for upcoming weeks  
**So that** I can plan ahead and indicate future unavailability (vacation, etc.)

**Task Flow:**
1. User sees week navigation controls
2. User navigates forward to view next week
3. Week view updates to display selected week's dates
4. User configures availability for that week using standard controls or presets
5. User can continue navigating to additional future weeks
6. User can return to current week at any time

**Information Required:**
- Week navigation (forward/backward)
- Day availability settings for each week

**Information Provided to User:**
- Week view updates to selected timeframe
- Availability settings saved per week
- Week identifier display (e.g., "Week of March 10")

**Edge Cases:**
- Future range limit: May restrict to 4-8 weeks ahead
- Past weeks: Cannot edit historical weeks (read-only or hidden)
- Current week changes: Immediate effect on shift matching

---

## Staff: Payments

### Purpose
Track earnings, view payment history, and access early pay options. Workers can see their financial data and request faster payment when needed.

### User Stories

#### Story 1: View Earnings Summary
**As a** worker  
**I want to** access my current balance and earnings trends over time  
**So that** I understand my earned income and payment schedule

**Task Flow:**
1. User accesses payments and earnings area
2. System presents financial overview displaying:
   - **Balance Information**:
     - Total account balance (prominently displayed)
     - Amount available for early payment access
     - Next scheduled payout date
   - **Earnings Trend Analysis**:
     - Earnings data over time
     - Selectable time periods (Day, Week, Month)
   - **Payment History Preview**:
     - Recent transaction summary
3. User reviews financial summary information

**Information Required:**
- None (view-only access to financial data)

**Information Provided to User:**
- Current balance amount
- Earnings trend analysis
- Payment history preview

**Edge Cases:**
- No earnings yet: Display $0.00 with message "Complete shifts to start earning"
- Negative balance: Alert indication if deductions exceed earnings
- Pending payments: Clear indication of amounts in processing

---

#### Story 2: View Payment History
**As a** worker  
**I want to** access detailed records of all my payments and withdrawals  
**So that** I can track my complete financial transaction history

**Task Flow:**
1. User navigates to Payment History section or accesses complete history
2. System presents comprehensive transaction list displaying:
   - Date and time
   - Transaction description (Shift payment, Early pay, ATM withdrawal)
   - Amount (positive for deposits, negative for withdrawals)
   - Status (Completed, Pending, Failed)
   - Payment method (Direct deposit, Early pay, etc.)
3. User can apply filters:
   - Time period (Day, Week, Month)
   - Transaction type (All, Deposits, Withdrawals)
4. User can access detailed information for any transaction

**Information Required:**
- Optional: Period filter selection
- Optional: Transaction type filter
- Transaction selection for details

**Information Provided to User:**
- Filtered transaction inventory
- Detailed information for individual transactions

**Edge Cases:**
- No transaction history: Message "No payment history yet"
- Failed transaction: Display with error indicator and explanation
- Large history: Progressive loading or pagination mechanism

---

#### Story 3: Request Early Payment
**As a** worker  
**I want to** request early access to my earned but not yet paid balance  
**So that** I can access funds immediately when needed

**Task Flow:**
1. User accesses early payment capability
2. System presents early payment option displaying:
   - Available balance for early access (e.g., $340.00)
   - Fee information (if applicable)
   - Processing timeframe (e.g., "Instant" or "Within 1 hour")
3. User specifies amount to request:
   - Amount input (currency)
   - Cannot exceed available balance
4. User selects payment destination:
   - Bank account (if registered)
   - Debit card (if supported)
5. User reviews transaction summary:
   - Requested amount
   - Processing fee (if any)
   - Net amount to receive
   - Destination account (masked last 4 digits)
6. User confirms early payment request
7. System processes request
8. Success confirmation: "Early pay request submitted. Funds arriving soon!"
9. Transaction appears in payment history with "Pending" status

**Information Required:**
- Amount to request (currency value)
- Payment destination selection
- Transaction confirmation

**Information Provided to User:**
- Available balance for early access
- Fee calculation and disclosure
- Success confirmation
- Updated balance reflecting request
- New transaction in history

**Edge Cases:**
- **Insufficient balance**: Error "Not enough earned balance for early pay"
- **No registered account**: Prompt "Add a bank account to use early pay" with profile navigation
- **Minimum amount requirement**: Error "Minimum early pay amount is $20"
- **Daily limit reached**: Error "You've reached your daily early pay limit. Try again tomorrow."
- **Fee disclosure**: Clear presentation of all fees before confirmation
- **Network issues**: Queue request for submission when connected

---

## Staff: Profile

### Purpose
Central hub for worker's personal information, profile completion tracking, reliability score, and navigation to profile sections (onboarding, compliance, finances, support).

### User Stories

#### Story 1: View Profile Overview
**As a** worker  
**I want to** access my profile information and completion status  
**So that** I understand requirements and how clients evaluate my reliability

**Task Flow:**
1. User accesses profile area
2. System presents profile overview displaying:
   - **Profile Header Information**:
     - Profile picture
     - Full name
     - Reliability score (0-5 stars or percentage)
   - **Reliability Statistics**:
     - Total shifts completed (count)
     - On-time arrival percentage
     - Cancellation count
   - **Profile Completion Status** (4 categories):
     - Onboarding (Personal info, experience, preferences)
     - Compliance (Tax forms, documents, certificates)
     - Finances (Bank account, payment info)
     - Support (FAQs, privacy settings)
   - Each section displaying:
     - Section name
     - Completion percentage (e.g., "75% complete")
     - Outstanding items (e.g., "2 items remaining")
     - Access to continue completion
3. User reviews overview information
4. User can access any section for completion

**Information Required:**
- None (view-only access to profile data)

**Information Provided to User:**
- Complete profile information display
- Reliability score and detailed statistics
- Completion status for all sections
- Navigation to all profile sections

**Edge Cases:**
- Profile 100% complete: Success indicator "Your profile is complete!"
- Low reliability score: Tips for improvement displayed
- Critical items missing: Alert "Complete [Section] to unlock full access"
- First-time view: Guidance on completing essential sections first

---

#### Story 2: Navigate to Profile Sections
**As a** worker  
**I want to** easily access different parts of my profile to complete or update information  
**So that** I can maintain an accurate and complete profile

**Task Flow:**
1. Worker reviews profile overview
2. Worker selects a profile section (Onboarding, Compliance, Finances, or Support)
3. System loads that section's data and features
4. Worker completes tasks within that section (see Profile Sections stories)
5. Worker returns to profile overview
6. Completion percentage recalculates to reflect changes

**Information Required:**
- Section selection (Onboarding, Compliance, Finances, or Support)

**Information Provided to User:**
- Selected section data and available actions
- Updated completion status after returning

---

#### Story 3: View Reliability Score Details
**As a** worker  
**I want to** understand how my reliability score is calculated  
**So that** I know how to improve it and understand how clients evaluate me

**Task Flow:**
1. Worker views reliability score on profile
2. Worker requests detailed score information
3. System provides score breakdown showing:
   - Score breakdown (factors: on-time arrivals, completions, cancellations, client ratings)
   - How each factor impacts score
   - Tips for improvement
4. Worker reviews information
5. Worker dismisses details and returns to profile

**Information Required:**
- Request for reliability score details

**Information Provided to User:**
- Score breakdown by factor (on-time arrivals, completions, cancellations, client ratings)
- Factor impact explanations
- Improvement suggestions

---

#### Story 4: Sign Out from Profile
**As a** worker  
**I want to** sign out of my account  
**So that** my information is secure when I'm not using the app

**Task Flow:**
1. Worker navigates to sign out option in profile
2. Worker initiates sign out action
3. System requests sign out confirmation: "Are you sure you want to sign out?"
4. Worker confirms sign out
5. System terminates user session
6. System returns worker to authentication state

**Information Required:**
- Sign out initiation
- Confirmation of sign out intent

**Information Provided to User:**
- Sign out confirmation request
- Session termination confirmation
- Return to authentication state

**Edge Cases:**
- Cancel confirmation: Session remains active, worker returns to profile

---

## Staff: Profile Sections

### Purpose
Detailed sub-features for completing different aspects of a worker's profile. Organized into 4 categories: Onboarding, Compliance, Finances, and Support.

### Categories
1. **Onboarding** - Personal info, experience, emergency contacts, attire
2. **Compliance** - Tax forms, identity documents, certificates
3. **Finances** - Bank account setup, timecard management
4. **Support** - FAQs, privacy & security settings

---

### Onboarding Section

#### Story 1: Complete Personal Information
**As a** worker  
**I want to** provide my personal details  
**So that** clients can identify me and I can receive important communications

**Task Flow:**
1. Worker accesses Onboarding → Profile Info section
2. System presents required personal information fields:
   - Full name (may be pre-filled from signup)
   - Date of birth
   - Email address
   - Secondary contact information
   - Profile photo
   - Language preference
   - Preferred work locations
3. Worker provides or updates information
4. Worker supplies profile photo:
   - Worker provides photo via camera capture or existing photo
   - Worker adjusts/crops photo if needed
   - Worker confirms photo selection
5. Worker submits information
6. System validates data and persists changes
7. System confirms: "Profile information updated"

**Information Required:**
- Full name
- Date of birth
- Email address
- Secondary contact information
- Profile photo (image file)
- Language preference
- Preferred work locations

**Information Provided to User:**
- Validation feedback for each field
- Success confirmation
- Updated profile data

**Edge Cases:**
- Invalid email: Validation error message
- Age under 18: May require additional verification
- Photo too large: Compression applied or size error message

---

#### Story 2: Document Work Experience
**As a** worker  
**I want to** list my work history and skills  
**So that** clients see my qualifications and I'm matched to appropriate jobs

**Task Flow:**
1. Worker accesses Onboarding → Experience section
2. System displays existing experience entries (if any)
3. Worker initiates adding new experience entry
4. System requests experience details:
   - Job title/role
   - Years of experience
   - Skills (Server, Cook, Driver, etc.)
   - References (optional)
5. Worker provides experience information
6. Worker submits entry
7. System adds experience to worker's profile
8. Worker can add multiple entries
9. Worker can modify or remove entries

**Information Required:**
- Job title/role
- Years of experience (numeric)
- Skills (multi-select: Server, Cook, Driver, etc.)
- References (optional)

**Information Provided to User:**
- List of all experience entries
- Success confirmation for each operation

**Edge Cases:**
- No experience: Worker can skip or indicate "Entry Level"
- Maximum entries: System may limit to 5-10 entries

---

#### Story 3: Add Emergency Contact
**As a** worker  
**I want to** provide emergency contact information  
**So that** someone can be reached if something happens while I'm working

**Task Flow:**
1. Worker accesses Onboarding → Emergency Contact section
2. System displays existing contacts (if any)
3. Worker initiates adding new contact
4. System requests contact details:
   - Full name
   - Relationship (Spouse, Parent, Sibling, Friend)
   - Phone number
5. Worker provides contact information
6. Worker submits contact
7. System adds contact to worker's profile
8. Worker can add multiple contacts (primary, secondary)

**Information Required:**
- Contact full name
- Relationship type (Spouse, Parent, Sibling, Friend)
- Phone number

**Information Provided to User:**
- List of all emergency contacts
- Success confirmation

**Edge Cases:**
- Required for profile completion
- Workers can designate primary contact

---

#### Story 4: Upload Attire Photo
**As a** worker  
**I want to** upload photos showing my work attire  
**So that** clients can verify I meet dress code requirements

**Task Flow:**
1. Worker accesses Onboarding → Attire section
2. System provides instructions: "Take photos of yourself in appropriate work attire"
3. Worker initiates photo submission
4. Worker provides photo via camera capture or existing photo
5. System displays photo preview
6. Worker confirms photo or provides alternative
7. System stores photo in worker's profile
8. Worker can submit multiple photos (front view, full body, etc.)

**Information Required:**
- Attire photo (image file from camera or existing photo)
- Photo confirmation

**Information Provided to User:**
- Uploaded photos display
- Success confirmation
- Photo requirements (e.g., "Full body, professional attire")

**Edge Cases:**
- Photo requirements stated (e.g., "Full body, professional attire")
- Photos may require admin approval

---

### Compliance Section

#### Story 5: Upload Tax Forms
**As a** worker  
**I want to** upload required tax documentation  
**So that** I'm legally compliant and can receive payment

```mermaid
graph TD
    A[Start: Navigate to Compliance - Tax Forms] --> B[View Required Forms List]
    B --> C{Forms Uploaded?}
    C -->|No| D[See Required Forms<br/>W-4, W-9, State Tax]
    C -->|Yes| E[See Uploaded Status<br/>Completed Status Shown]
    D --> F[Tap Upload Form Button]
    F --> G{Choose Upload Method}
    G -->|Camera| H[Open Camera<br/>Capture Document]
    G -->|Gallery| I[Open Gallery<br/>Select Existing Photo]
    G -->|File| J[Open File Picker<br/>Select PDF]
    H --> K[Preview Captured Image]
    I --> K
    J --> K
    K --> L{Image Clear?}
    L -->|No| M[Retake or Choose Different]
    M --> G
    L -->|Yes| N[Confirm Upload]
    N --> O[System Processes<br/>OCR/Validation]
    O --> P{Valid Document?}
    P -->|No| Q[Show Error<br/>Please upload correct form]
    Q --> F
    P -->|Yes| R[Success: Form Uploaded]
    R --> S[Status Changes to Pending Review]
    S --> T[Admin Reviews if Required]
    T --> U{Approved?}
    U -->|Yes| V[Status: Verified]
    U -->|No| W[Status: Rejected - Reason Shown]
    W --> F
```

**Task Flow:**
1. Worker accesses Compliance → Tax Forms section
2. System displays list of required forms:
   - W-4 (Federal withholding)
   - W-9 (Tax identification)
   - State tax forms (if applicable)
3. System shows status for each form:
   - Not uploaded
   - Pending review
   - Approved
4. Worker selects form to upload and provides document:
   - Via camera capture
   - Via existing photo
   - Via PDF file selection
5. Worker captures or selects document
6. System displays document preview
7. Worker confirms submission
8. System performs basic validation (document type, clarity)
9. System confirms: "Tax form uploaded. Pending review."
10. Status changes to "Pending Review"
11. Admin reviews and approves/rejects
12. Worker receives approval status update

**Information Required:**
- Tax form document (image or PDF)
- Document confirmation

**Information Provided to User:**
- Upload progress
- Success confirmation
- Form status (Not uploaded, Pending, Approved, Rejected)
- Approval/rejection notifications

**Edge Cases:**
- **Blurry photo**: System may reject or warn "Document not clear. Please retake."
- **Wrong form**: Validation error "This doesn't appear to be a W-4 form"
- **Rejected by admin**: User receives notification with reason and option to re-upload
- **Signature required**: Form may require digital signature before upload
- **Expiration**: Some forms expire and require re-upload annually

---

#### Story 6: Upload Identity Documents
**As a** worker  
**I want to** verify my identity with required documents  
**So that** I can meet compliance requirements and be eligible to work

**Task Flow:**
1. Worker accesses Compliance → Documents section
2. System displays required documents:
   - Driver's license or state ID (both sides)
   - Social Security Number verification
   - Address verification (utility bill, lease, etc.)
3. Worker uploads each document (same process as tax forms)
4. System performs verification and routes to admin for review
5. Status updates to Approved when complete

**Information Required:**
- ID document photos (front and back)
- Social Security Number (secure entry or document)
- Address proof document

**Information Provided to User:**
- Upload confirmations for each document
- Verification status
- Approval notifications

**Edge Cases:**
- SSN must be securely transmitted and encrypted
- ID expiration date: System tracks and notifies before expiry
- Address verification may require recent document (within 60 days)

---

#### Story 7: Upload Professional Certificates
**As a** worker  
**I want to** upload professional licenses and certifications  
**So that** I can qualify for specialized shifts requiring credentials

**Task Flow:**
1. Worker accesses Compliance → Certificates section
2. System displays optional/required certificates based on roles:
   - Food Handler's Permit
   - Bartending License
   - Forklift Certification
   - CPR/First Aid
   - Background check status
3. Worker uploads applicable certificates
4. Worker provides expiration date for each certificate
5. System tracks expiration and sends renewal reminders
6. Admin reviews and approves certificates
7. System updates worker's eligible roles based on approved certificates

**Information Required:**
- Certificate documents (photos or PDFs)
- Certificate number (optional)
- Expiration date

**Information Provided to User:**
- List of certificates with expiration dates
- Renewal reminders (notifications)
- Newly unlocked roles

**Edge Cases:**
- Expired certificate: Warning displayed, worker cannot accept related shifts
- Background check status: May be handled separately
- Temporary certificates: Short-term expiration dates supported

---

### Finances Section

#### Story 8: Set Up Bank Account
**As a** worker  
**I want to** add my bank account information  
**So that** I can receive direct deposit payments

**Task Flow:**
1. Worker accesses Finances → Bank Account section
2. If no account on file, system presents option to add bank account
3. Worker initiates bank account setup
4. System requests account details:
   - Bank name
   - Account holder name
   - Account number
   - Routing number
   - Account type (Checking or Savings)
5. Worker provides banking information
6. Worker submits details
7. System may verify account (micro-deposits or instant verification)
8. System confirms: "Bank account added"
9. System displays masked account information (last 4 digits only)

**Information Required:**
- Bank name
- Account holder name
- Account number (secure)
- Routing number (9 digits, secure)
- Account type (Checking or Savings)

**Information Provided to User:**
- Masked account display (e.g., "••••1234")
- Account verification status

**Edge Cases:**
- Invalid routing number: Validation error
- Verification failed: Worker must confirm account via micro-deposits
- Multiple accounts: Workers can add backup account
- Edit or remove account: Modification and removal available

---

#### Story 9: View and Dispute Timecard
**As a** worker  
**I want to** view my recorded hours and dispute any errors  
**So that** I'm paid correctly for time worked

**Task Flow:**
1. Worker accesses Finances → Time Card section
2. System displays list of recent shifts with recorded hours:
   - Shift date
   - Check-in time
   - Check-out time
   - Break duration
   - Total hours
   - Pay amount
3. Worker selects a shift to view details
4. If hours are incorrect, worker initiates dispute
5. System requests dispute information:
   - What's wrong? (multiple options or free text)
   - Correct hours (manual entry)
   - Notes/explanation
6. Worker submits dispute
7. System notifies client/manager
8. System tracks dispute status (Submitted, Under Review, Resolved)

**Information Required:**
- Shift selection
- Dispute reason
- Corrected hours (numeric)
- Explanation

**Information Provided to User:**
- Timecard details for all shifts
- Dispute submission confirmation
- Dispute status updates

**Edge Cases:**
- Adjustment approved: Payment corrected
- Adjustment denied: Reason provided, worker can escalate
- Multiple disputes: May flag for review

---

### Support Section

#### Story 10: Access FAQs
**As a** worker  
**I want to** find answers to common questions  
**So that** I can resolve issues without contacting support

**Task Flow:**
1. Worker accesses Support → FAQs section
2. System displays FAQ categories:
   - Getting Started
   - Shifts & Scheduling
   - Payments
   - Technical Issues
3. Worker selects a category
4. System displays list of frequently asked questions for that category
5. Worker selects a question
6. System displays detailed answer
7. Worker can search FAQs using text query
8. If issue not resolved, worker can contact support

**Information Required:**
- Category selection
- Question selection
- Search query (optional)

**Information Provided to User:**
- FAQ categories list
- Questions and answers for selected category
- Search results matching query
- Contact support option

**Edge Cases:**
- No results for search: System shows "No matching FAQs" with Contact Support option
- Links in answers: May reference relevant sections or features

---

#### Story 11: Manage Privacy & Security
**As a** worker  
**I want to** control my privacy settings and account security  
**So that** my personal information is protected

**Task Flow:**
1. Worker accesses Support → Privacy & Security section
2. System presents security and privacy options:
   - **Change Password**:
     - Current password verification
     - New password entry (with strength indicator)
     - New password confirmation
   - **Two-Factor Authentication**:
     - Enable/disable 2FA
     - Setup instructions if enabling
   - **Privacy Settings**:
     - Profile visibility controls
     - Communication preferences
   - **Data Access**:
     - Download personal data (export to file)
     - Delete account (requires confirmation)
3. Worker makes desired changes
4. Worker saves changes
5. System provides confirmation for each change

**Information Required:**
- Current password (for password change)
- New password (secure)
- Password confirmation
- 2FA preference (enable/disable)
- Privacy preferences
- Data export request
- Account deletion confirmation

**Information Provided to User:**
- Success confirmations for each change
- 2FA setup instructions
- Data export file (when ready)
- Account deletion confirmation

**Edge Cases:**
- **Password requirements**: Minimum length, complexity rules enforced and displayed
- **2FA setup**: Requires phone or authenticator app
- **Delete account**: Multi-step confirmation with warnings about data loss
- **Data export**: May take time to prepare, delivered via email

---

# Glossary

### Client Application Terms

- **Client**: A business owner or manager who uses the app to request staffing and manage operations.
- **Coverage**: The percentage or count of filled positions versus total positions needed for a given time period. 100% coverage means all shifts are filled.
- **Cost Center**: An accounting designation for tracking expenses by location or department within a business.
- **Hub**: A physical business location or venue where staff work (e.g., restaurant, warehouse, event venue).
- **Hub Manager**: A supervising employee at a hub location who oversees on-site operations.
- **Invoice**: A bill for services rendered, detailing worker hours, pay rates, and total costs for completed shifts.
- **NFC Tag**: Near Field Communication tag used for quick check-ins via phone tap at a physical location.
- **Order**: A staffing request created by a client specifying positions needed, dates, times, and location.
  - **One-Time Order**: Single-day staffing request
  - **Recurring Order**: Weekly pattern repeated over a limited period (max 29 days)
  - **Permanent Order**: Ongoing staffing for certain days with no end date
  - **Rapid Order**: Emergency/expedited staffing request
- **Position**: A role or job function within a shift (e.g., Server, Cook, Bartender, Warehouse Associate).
- **Vendor**: A staffing agency or organization providing workers (may be internal to KROW).

### Staff Application Terms

- **Auto-Match**: A feature that automatically notifies workers of shifts matching their preferences and availability.
- **Break**: A rest period during a shift, which is tracked separately and deducted from billable hours.
- **Check-In**: The action of confirming arrival at a shift location, typically with location verification.
- **Check-Out**: The action of ending a shift and recording total time worked.
- **Commute Mode**: A tracking feature showing the worker's real-time location and ETA to the venue.
- **Early Pay**: A service allowing workers to access earned wages before the regular pay date, often for a fee.
- **Geo-Fencing**: Location verification that ensures a worker is within a certain distance (500m) of the venue.
- **Marketplace**: The "Find Shifts" tab where workers browse and book available shifts.
- **OTP (One-Time Password)**: A temporary 6-digit code sent via SMS for authentication.
- **Profile Completion Gate**: A requirement that workers complete certain profile sections before they can book shifts.
- **Reliability Score**: A rating (0-5 or percentage) based on attendance, punctuality, completion rate, and client feedback.
- **Shift**: A scheduled work period with specific start/end times, location, and role.
- **Timecard**: A record of hours worked, including check-in, check-out, and break times.

### Shared Terms

- **Business Location**: See Hub above.
- **Role**: A job function or position type (e.g., Server, Cook, Driver).
- **Staff/Worker**: A person who accepts and performs shifts through the KROW platform.
- **Status**: The current state of an order, shift, invoice, or document (e.g., Pending, Approved, Completed, Cancelled).

---

## Document End

**Total Features Documented**: 18 (9 Client + 9 Staff)  
**Total User Stories**: 60+  
**Total Mermaid Diagrams**: 4

This document provides a complete functional overview of the KROW Workforce Management Platform from a design perspective, enabling designers to understand user needs, flows, and interactions without needing to understand the underlying code implementation.