Krow-workspace/docs/05-project-onboarding-master.md

KROW Workforce Platform - Project Onboarding Master Document

Version: 1.0 Last Updated: 2026-01-11 Purpose: Source of Truth for Team Onboarding & Sprint Planning

---

Table of Contents

1. Project Vision & Business Value
2. System Architecture (GCP Migration)
3. Core Domain Logic
4. Feature Gap Analysis
5. Data Connect & Development Strategy
6. Definition of Done (DoD)

---

1. Project Vision & Business Value

1.1 What is KROW?

KROW is a workforce management platform that connects businesses (clients) with temporary/gig workers (staff) for event-based staffing needs. The platform handles the complete lifecycle from job posting to payment processing.

1.2 The Problem We Solve

Stakeholder	Pain Point	KROW Solution
Businesses	Finding qualified temp workers is time-consuming and unreliable	Instant access to pre-verified workers with ratings and certifications
Workers	Inconsistent gig opportunities, delayed payments, opaque earnings	Centralized shift discovery, real-time earnings tracking, transparent payment
Administrators	Manual coordination between clients and workers, paper-based time tracking	Automated assignment, QR/NFC clock-in, digital invoicing

1.3 Core Value Proposition

KROW = Uber for Event Staffing

• For Clients: Post events, define shifts, get matched workers, track time, pay invoices
• For Staff: Browse shifts, accept gigs, clock in/out, track earnings, get paid
• For Admins: Manage workforce, verify profiles, resolve disputes, generate reports

1.4 Business Model

1. Service Fees: Markup on worker hourly rates (configurable per business)
2. Premium Add-ons: Optional services (uniforms, equipment, expedited matching)
3. Enterprise Contracts: Long-term staffing agreements with volume discounts

1.5 Strategic Objective

Mission: Achieve complete technical independence by consolidating the KROW platform onto a single, robust, and maintainable ecosystem: Firebase & Google Cloud.

Guiding Principles:

1. Velocity & Focus: Maximize productivity with Firebase Data Connect and generated SDKs
2. Unified Backend: Single backend (Data Connect) powers all applications (Web, iOS, Android)
3. Scalability & Low Overhead: Managed services minimize operational burden
4. Data Ownership: Full control over PostgreSQL database for complex reporting
5. Base44 as Design Accelerator: Treat Base44 as a prototyping tool, not a system to migrate
6. Automation as Force Multiplier: Automate via Makefile and CI/CD pipelines

---

2. System Architecture (GCP Migration)

2.1 Migration Overview

LEGACY (Digital Ocean)          ──────────►          NEW (Google Cloud Platform)
├── PHP/Laravel Backend                              ├── Firebase Data Connect (GraphQL)
├── Laravel Nova Admin                               ├── Cloud Functions (Business Logic)
├── GraphQL (Lighthouse)                             ├── Cloud Run (Heavy Compute)
├── PostgreSQL (Self-managed)     ──────────►        ├── Cloud SQL (Managed PostgreSQL)
├── Digital Ocean Spaces          ──────────►        ├── Cloud Storage
└── Firebase Auth + FCM           ──────────►        └── Firebase Auth + FCM (unchanged)

2.2 New Architecture Diagram

graph TB
    subgraph Clients["Client Applications"]
        direction LR
        Mobile["Flutter Apps<br/>(Client + Staff)"]
        Web["Vite/React<br/>(Business + Admin)"]
    end

    subgraph Firebase["Firebase Services"]
        direction LR
        Auth["Firebase Auth + FCM"]
        DataConnect["Firebase Data Connect<br/>GraphQL API + Generated SDKs"]
    end

    subgraph Backend["Backend Services"]
        direction LR
        CloudRun["Cloud Run"]
        CloudFunctions["Cloud Functions"]
    end

    subgraph AI["AI Services"]
        VertexAI["Vertex AI / Gemini"]
    end

    subgraph Data["Data Layer"]
        direction LR
        CloudSQL["Cloud SQL<br/>(PostgreSQL)"]
        Storage["Cloud Storage"]
    end

    subgraph Security["Security & Compliance"]
        direction LR
        SecServices["Cloud IAM | Monitoring | Secret Manager"]
        Compliance["GDPR Ready | SOC 2 Type II | HIPAA Eligible"]
    end

    Mobile -->|"GraphQL SDK"| DataConnect
    Web -->|"GraphQL SDK"| DataConnect
    Mobile -.-> Auth
    Web -.-> Auth

    Mobile -->|"HTTP/REST"| CloudRun
    Web -->|"HTTP/REST"| CloudRun
    CloudFunctions -.->|"Events"| CloudRun

    DataConnect --> CloudSQL
    CloudRun --> CloudSQL
    CloudFunctions --> CloudSQL
    CloudRun --> Storage

    CloudRun --> VertexAI
    CloudFunctions --> VertexAI

2.3 Technology Stack Comparison

Component	Legacy (Current)	New (Target)
Backend Framework	PHP/Laravel	Firebase Data Connect + Cloud Functions
API Layer	GraphQL (Lighthouse)	Firebase Data Connect (GraphQL)
Admin Panel	Laravel Nova	Custom React Admin (or Firebase Extension)
Database	PostgreSQL (DO Droplet)	Cloud SQL (Managed PostgreSQL)
File Storage	Digital Ocean Spaces	Cloud Storage
Authentication	Firebase Auth	Firebase Auth (unchanged)
Notifications	FCM	FCM (unchanged)
Mobile Apps	Flutter	Flutter (code restructure with Melos)
Web App	Inertia.js + Vue	Vite + React
AI/ML	None	Vertex AI / Gemini
Hosting	Digital Ocean	Firebase Hosting + Cloud Run

2.4 Key Architecture Decisions

1. Firebase Data Connect as Primary API:

   • Auto-generates type-safe SDKs for all clients
   • Eliminates API versioning headaches
   • Direct PostgreSQL access with GraphQL abstraction

2. Cloud Functions for Business Logic:

   • Email sending, AI invocations, file processing
   • Event-driven architecture for async operations
   • Clean separation from data layer

3. PostgreSQL Retention:

   • Full data ownership and portability
   • Complex queries and reporting capabilities
   • Industry-standard for enterprise requirements

4. Monorepo Structure:

   krow-workforce-web/
   ├── apps/
   │   ├── web-dashboard/     # Vite + React
   │   ├── mobile-client/     # Flutter (business app)
   │   └── mobile-staff/      # Flutter (worker app)
   ├── backend/
   │   ├── dataconnect/       # Firebase Data Connect schemas
   │   └── functions/         # Cloud Functions
   ├── firebase/              # Firebase config
   ├── internal/
   │   └── launchpad/         # Internal tools & prototypes
   └── docs/                  # Documentation
   

---

3. Core Domain Logic

3.1 Domain Entities Overview

The KROW platform has 49 domain entities organized into 8 logical groups:

┌────────────────────────────────────────────────────────────────────┐
│                        KROW DOMAIN MODEL                           │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │   USERS &   │    │  BUSINESS & │    │  EVENTS &   │             │
│  │ MEMBERSHIP  │    │ ORGANIZATION│    │   SHIFTS    │             │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤             │
│  │ User        │    │ Business    │    │ Event       │             │
│  │ Staff       │    │ BusinessSet │    │ EventShift  │             │
│  │ Membership  │    │ Hub         │    │ Position    │             │
│  │ BizMember   │    │ HubDept     │    │ Assignment  │             │
│  │ HubMember   │    │ BizContract │    │ WorkSession │             │
│  └─────────────┘    └─────────────┘    └─────────────┘             │
│                                                                    │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │  SKILLS &   │    │  FINANCIAL  │    │  RATINGS &  │             │
│  │   CERTS     │    │   PAYROLL   │    │  PENALTIES  │             │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤             │
│  │ Skill       │    │ Invoice     │    │ StaffRating │             │
│  │ SkillCat    │    │ InvoiceItem │    │ PenaltyLog  │             │
│  │ StaffSkill  │    │ InvDecline  │    │ BizStaffPref│             │
│  │ Certificate │    │ StaffPayment│    │             │             │
│  │ SkillKit    │    │             │    │             │             │
│  └─────────────┘    └─────────────┘    └─────────────┘             │
│                                                                    │
│  ┌─────────────┐    ┌─────────────┐                                │
│  │   STAFF     │    │   SUPPORT   │                                │
│  │   PROFILE   │    │    CONFIG   │                                │
│  ├─────────────┤    ├─────────────┤                                │
│  │ EmergencyC  │    │ Addon       │                                │
│  │ BankAccount │    │ Tag         │                                │
│  │ Accessibl   │    │ Media       │                                │
│  │ Schedule    │    │ WorkingArea │                                │
│  └─────────────┘    └─────────────┘                                │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

3.2 Key Entity Definitions

User & Authentication

Entity	Description	Key Fields
User	Base auth entity (Firebase)	id, email, phone, role
Staff	Worker profile	auth_provider_id, name, email, phone, status, address, avatar, live_photo
Membership	Polymorphic org membership	user_id, memberable_id, memberable_type, role

Staff Status Flow:

registered → pending → completed_profile → verified → [active | blocked | inactive]

Business & Organization

Entity	Description	Key Fields
Business	Client company	name, registration, status, avatar
BusinessSetting	Payroll config	prefix, overtime, clock_in, clock_out
Hub	Branch location	business_id, name, address, status
HubDepartment	Dept within hub	hub_id, name

Events & Shifts

Entity	Description	Key Fields
Event	Job posting	business_id, hub_id, name, date, status, contract_type
EventShift	Work session	event_id, name, address
EventShiftPosition	Job opening	shift_id, skill_id, count, rate, start_time, end_time, break
EventShiftPositionStaff	Assignment	staff_id, position_id, status, clock_in, clock_out

Event Status Flow:

draft → pending → assigned → confirmed → active → finished → completed → closed
                                                           ↘ under_review

Assignment Status Flow:

assigned → confirmed → ongoing → completed
         ↘ decline_by_staff → [penalty logged]
         ↘ canceled_by_staff → [penalty logged]
         ↘ no_showed → [penalty logged]

Skills & Certifications

Entity	Description	Key Fields
Skill	Job category	category_id, name, price
StaffSkill	Worker qualification	staff_id, skill_id, level, experience, status
Certificate	Required credential	name, required
SkillKit	Uniform/equipment req	skill_id, name, is_required, type

Skill Levels: beginner | skilled | professional

Financial & Payroll

Entity	Description	Key Fields
Invoice	Business bill	event_id, business_id, status, total, work_amount, addons_amount
InvoiceItem	Line item	invoice_id, staff_id, work_hours, rate, amounts
StaffPayment	Worker payout	staff_id, assignment_id, amount, status, paid_at

Invoice Status Flow:

open → disputed → resolved → verified → paid/reconciled
     ↘ overdue

3.3 Core Business Workflows

Workflow 1: Event Lifecycle

sequenceDiagram
    participant Client as Client App
    participant API as Backend API
    participant Admin as Admin
    participant Staff as Staff App

    Note over Client,API: 1. Event Creation
    Client->>API: Create Event with Shifts & Positions
    API-->>Client: Event Created (Draft)
    Client->>API: Publish Event
    API-->>Client: Event Published

    Note over Admin,API: 2. Staff Assignment
    Admin->>API: Assign Staff to Shift
    API-->>Admin: Assignment Confirmed
    API->>Staff: Notification: New Shift

    Note over Staff,API: 3. Shift Acceptance
    Staff->>API: Accept Shift
    API-->>Staff: Shift Confirmed

    Note over Client,Staff: 4. Day of Event
    Client->>Client: Generate QR Code
    Staff->>Staff: Scan QR Code
    Staff->>API: Clock In
    Staff->>API: Clock Out

    Note over Client,API: 5. Post-Event
    Client->>API: Rate Staff
    API->>API: Generate Invoice
    Client->>API: Approve Invoice

Workflow 2: Staff Onboarding

1. Registration (Firebase Phone Auth)
   ├── Create Staff record (status: registered)
   └── Profile created with auth_provider_id

2. Profile Completion
   ├── Personal info (name, email, address)
   ├── Avatar upload
   ├── Emergency contacts
   └── Bank account details

3. Skills Declaration
   ├── Add skills with level/experience
   └── Status: pending → verified (admin)

4. Certification Upload
   ├── Upload certificates
   └── Status: pending → verified (admin)

5. Equipment Confirmation
   ├── Confirm uniforms per skill
   ├── Confirm equipment per skill
   └── Upload photos as proof

6. Profile Submission
   ├── Complete verification checklist
   └── Status: completed_profile → verified

Workflow 3: Payroll Calculation

Work Hours = (clock_out - clock_in) - break_duration

Overtime Rules:
├── Regular Hours (1x):     hours <= 8
├── Overtime Hours (1.5x):  8 < hours <= 10
└── Doubletime Hours (2x):  hours > 10

Payment = (regular_hours × rate × 1.0)
        + (overtime_hours × rate × 1.5)
        + (doubletime_hours × rate × 2.0)
        + addons_amount

3.4 API Structure (Legacy Reference)

Client (Business) API

Queries:

• client_hubs - Get accessible hubs
• client_events(status) - Paginated events
• client_invoices(status) - Paginated invoices
• client_business_skills - Business skill catalog

Mutations:

• client_create_event(input) - Create event
• client_publish_event(id) - Publish event
• track_client_clockin/clockout - Manual time tracking
• rate_client_staff(input) - Rate worker

Staff (Worker) API

Queries:

• me - Current staff profile
• staff_shifts(status) - Paginated shifts
• staff_payments(status) - Paginated payments
• verification_check_list - Onboarding progress

Mutations:

• accept_shift(position_id) - Accept shift
• decline_shift(position_id, reason) - Decline with penalty
• track_staff_clockin/clockout - Time tracking
• update_staff_* - Profile updates

---

4. Feature Gap Analysis

4.1 Legacy Feature Inventory

Client Mobile App (Flutter)

Feature	Files	Status	Priority
Event Creation & Management	40	Production	P0
Event List & Details	21	Production	P0
Invoice Management	29	Production	P0
Hub Management	11	Production	P1
Staff Assignment View	4	Production	P0
Manual Clock In/Out	9	Production	P0
Staff Rating	9	Production	P1
Notifications	12	Production	P1
Profile Management	11	Production	P2

Total: 272 Dart files, 24,690 LOC, 12 features

Staff Mobile App (Flutter)

Feature	Files	Status	Priority
Authentication (Phone)	9	Production	P0
Shift Management	70	Production	P0
Earnings & Payments	32	Production	P0
Profile (Complete)	211	Production	P0
Check List (Verification)	11	Production	P1
QR Scanner	1	Production	P0
Support	2	Production	P2

Total: 430 Dart files, 34,676 LOC, 10 features

Backend (PHP/Laravel)

Component	Count	Status
Eloquent Models	49	Production
Actions	19	Production
GraphQL Queries	30+	Production
GraphQL Mutations	40+	Production
Nova Resources	20+	Production

Total: 353 PHP files, 28,675 LOC

4.2 Web Prototype Analysis (Source Code)

Location: internal/launchpad/prototypes-src/web/

The web prototype is a fully functional React application with rich business logic:

4.2.1 Feature Routes (38 Routes)

Category	Route	Component	Roles
Overview	/dashboard/admin	AdminDashboard	Admin
	/dashboard/client	ClientDashboard	Client
	/dashboard/vendor	VendorDashboard	Vendor
	/savings	SavingsEngine	All
	/performance	VendorPerformance	Vendor, Admin
Operations	/orders	OrderList	Admin
	/orders/client	ClientOrderList	Client
	/orders/vendor	VendorOrderList	Vendor
	/orders/:id	OrderDetail	All
	/orders/:id/edit	EditOrder	All
	/schedule	Schedule	All
	/availability	StaffAvailability	All
	/tasks	TaskBoard	All
Marketplace	/marketplace	VendorMarketplace	Client, Admin
	/marketplace/compare	CompareRates	Client, Admin
Workforce	/staff	StaffList	All
	/staff/add	AddStaff	All
	/staff/:id/edit	EditStaff	All
	/onboarding	OnboardingFlow	All
	/teams	TeamList	All
	/teams/create	CreateTeam	All
	/teams/:id	TeamDetail	All
	/compliance	ComplianceDashboard	Vendor, Admin
	/documents	DocumentVault	Vendor, Admin
Finance	/invoices	InvoiceList	All
	/invoices/new	InvoiceEditor	All
	/invoices/:id	InvoiceDetail	All
Business	/clients	ClientList	Vendor, Admin
	/clients/add	AddClient	Vendor, Admin
	/clients/:id/edit	EditClient	Vendor, Admin
	/rates	ServiceRates	Vendor, Admin
Analytics	/reports	ReportsDashboard	All
	/activity	ActivityLog	Vendor, Admin
Communication	/messages	MessageCenter	All
	/tutorials	TutorialList	Client, Admin
Support	/support	SupportCenter	Client, Admin

4.2.2 Business Logic Implemented (Client-Side)

1. Overtime Calculator (logic/OvertimeCalculator.ts)

// State-specific OT/DT rules (California vs Federal)
STATE_RULES = {
  CA: { dailyOT: 8, dailyDT: 12, weeklyOT: 40, seventhDayDT: true },
  DEFAULT: { dailyOT: null, weeklyOT: 40 }
}
// Returns: status (GREEN/AMBER/RED), otHours, dtHours, costImpact

2. Smart Assignment Engine (logic/SmartAssignmentEngine.ts)

// Multi-factor scoring algorithm
Factors: Skill Match, Reliability Score, Vendor Priority,
         Fatigue Level, Compliance, Proximity, Cost Optimization
// Features: Double-booking detection, Auto-fill shifts

3. Conflict Detection (logic/ConflictDetection.ts)

// Detects: Staff overlap, Venue overlap, Buffer time violations
// Supports: Multi-day events, Time buffers, Severity levels

4. Order Status Utils (logic/OrderStatusUtils.ts)

• Status color mapping
• Status transition rules

5. Double Booking Validator (logic/DoubleBookingValidator.ts)

• Validates staff assignments across events

4.2.3 TypeScript Data Models (30+ Types)

Type	Fields	Maps to Legacy
User	id, email, role, user_role, preferred_vendor_id, dashboard_layout	User + BusinessMember
Staff	id, employee_name, position, rating, reliability_score, vendor_id	Staff
Event	id, event_name, date, status, shifts, assigned_staff, is_rapid, buffer_time	Event
Shift	roles[]	EventShift
ShiftRole	role, count, start_time, end_time, bill_rate, pay_rate	EventShiftPosition
StaffAssignment	staff_id, staff_name, role	EventShiftPositionStaff
Invoice	id, invoice_number, status, amount, roles[], disputed_items	Invoice + InvoiceItem
Business	id, business_name, hubs[], favorite_staff, blocked_staff, erp_*	Business
Vendor	id, legal_name, region, approval_status, markup, fee, rates[]	NEW
VendorRate	id, vendor_name, role_name, client_rate, employee_wage, markup_%	NEW
Team	id, team_name, owner_id, members, hubs, favorite_staff, blocked_staff	Business context
TeamMember	id, team_id, member_name, email, role, department, hub	Membership
TeamHub	id, team_id, hub_name, departments[]	Hub + HubDepartment
Task	id, task_name, priority, status, assigned_members, files	NEW
Certification	id, employee_id, certification_type, status, expiry_date	StaffCertificate
WorkerAvailability	staff_id, availability_status, need_work_index, utilization_%	NEW
Conversation	id, subject, participants[], last_message	NEW
ActivityLog	id, title, description, activity_type, icon_type	ActivityLog

4.3 Feature Gap Matrix (Updated)

Feature Area	Legacy Mobile	Web Prototype	Gap Status
Auth & Onboarding	Full (Phone)	Basic (Email)	Merge approaches
Event/Order CRUD	Full	Full + Enhanced	Prototype ahead
Shift Management	Full	Full + Scheduler	Prototype ahead
Time Tracking (QR/NFC)	Full	None	Legacy only
Invoice Generation	Full	Full + Templates	Prototype ahead
Payroll Calculation	Backend only	Client-side OT calc	Port to backend
Staff Profile	Full (211 files)	Basic	Legacy ahead
Skills & Certs	Full	Compliance Dashboard	Legacy ahead
Ratings & Penalties	Full	None explicit	Legacy only
Notifications	Full	None	Legacy only
Admin Dashboard	Nova	3 Role Dashboards	Prototype ahead
Vendor Management	None	Full Marketplace	Prototype only
Smart Assignment	None	AI Engine	Prototype only
Conflict Detection	None	Full	Prototype only
Savings Engine	None	Full	Prototype only
Task Board	None	Full	Prototype only
Messaging	None	Full	Prototype only
Reports	Basic	Advanced Templates	Prototype ahead
Teams/Organizations	Membership	Full Team Mgmt	Prototype ahead
Worker Availability	Schedule	Predictive	Prototype ahead

4.4 NEW Features in Prototype (Not in Legacy)

These are new capabilities to be implemented:

1. Savings Engine - Cost optimization recommendations
2. Vendor Marketplace - Vendor discovery and comparison
3. Smart Assignment Engine - AI-powered worker matching
4. Conflict Detection - Staff/venue/buffer conflict alerts
5. State-Specific OT Calculator - California labor law compliance
6. Task Board - Project management within platform
7. Rate Cards & Compare Rates - Pricing transparency
8. Worker Availability Prediction - Utilization scoring
9. Report Templates - Scheduled, exportable reports
10. ERP Integration Settings - Enterprise system connectivity
11. Multi-Dashboard by Role - Admin/Client/Vendor views
12. Messaging Center - In-app communication

4.5 Legacy Features Missing in Prototype

These must be ported from legacy:

1. Phone Authentication - Firebase phone auth flow
2. QR/NFC Clock In/Out - Mobile time tracking
3. Staff Profile Completion Wizard - 9-step verification
4. Skills & Skill Kits - Uniform/equipment confirmation
5. Certificate Upload & Verification - Document management
6. Penalty System - Decline/cancel/no-show tracking
7. Staff Rating by Business - Performance reviews
8. Payment Workflow - Staff payout confirmation
9. Emergency Contacts - Worker safety info
10. Bank Account Management - Payout details
11. Push Notifications - FCM integration
12. Geofencing - Location-based clock validation

4.6 Migration Strategy

┌─────────────────────────────────────────────────────────────────┐
│                    FEATURE MIGRATION PRIORITY                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  P0 - MUST HAVE (Sprint 3-4)                                    │
│  ├── Auth (Phone + Email)                                       │
│  ├── Event/Order CRUD                                           │
│  ├── Staff Profile Basics                                       │
│  ├── Invoice List/Detail                                        │
│  └── Dashboard (by role)                                        │
│                                                                 │
│  P1 - SHOULD HAVE (Sprint 5-6)                                  │
│  ├── Clock In/Out (QR at minimum)                               │
│  ├── Smart Assignment                                           │
│  ├── Conflict Detection                                         │
│  ├── Staff Verification Workflow                                │
│  └── Notifications                                              │
│                                                                 │
│  P2 - NICE TO HAVE (Sprint 7+)                                  │
│  ├── Savings Engine                                             │
│  ├── Vendor Marketplace                                         │
│  ├── Advanced Reports                                           │
│  ├── Task Board                                                 │
│  └── Messaging                                                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

4.7 Mobile Prototype Analysis (Source Code)

4.7.1 Mobile Client App (Flutter)

Location: internal/launchpad/prototypes-src/mobile/client/

Routes (22 screens):

Category	Route	Screen	Description
Auth	/client-get-started	GetStarted	Welcome screen
	/client-sign-in	SignIn	Email/password login
	/client-sign-up	SignUp	Registration
Orders	/create-order	CreateOrder	Order type selector
	/create-order/rapid	RapidOrderFlow	NEW: Voice-enabled URGENT orders
	/create-order/one-time	OneTimeOrderFlow	Single event
	/create-order/recurring	RecurringOrderFlow	Repeating schedule
	/create-order/permanent	PermanentOrderFlow	Ongoing staffing
Main Nav	/client-coverage	Coverage	Staffing coverage dashboard
	/client-billing	Billing	Invoice management
	/client-home	Home	Main dashboard
	/client-shifts	Shifts	Active orders
	/client-reports	Reports	Analytics hub
Reports	/daily-ops-report	DailyOps	NEW: Daily operations
	/spend-report	Spend	Cost analysis
	/forecast-report	Forecast	NEW: Predictive staffing
	/performance-report	Performance	Vendor/staff metrics
	/no-show-report	NoShow	Attendance tracking
	/coverage-report-detail	CoverageDetail	Coverage analytics
Other	/verify-worker-attire	VerifyAttire	NEW: Uniform check
	/client-hubs	Hubs	Location management
	/client-settings	Settings	Preferences

Key NEW Features:

• RAPID Orders - Voice-enabled urgent staffing requests ("Need 2 cooks ASAP")
• 4 Order Types - One-time, Rapid, Recurring, Permanent
• Forecast Reports - Predictive staffing needs
• Verify Worker Attire - Photo verification of uniforms

---

4.7.2 Mobile Staff App (Flutter)

Location: internal/launchpad/prototypes-src/mobile/staff/

Routes (35+ screens):

Category	Route	Screen	Description
Auth	/get-started	GetStarted	Welcome
	/phone-verification	PhoneVerification	OTP flow
	/profile-setup	ProfileSetup	Initial setup
Main Nav	/shifts	Shifts	Available/assigned shifts
	/payments	Payments	Earnings overview
	/worker-home	Home	Dashboard
	/clock-in	ClockIn	Swipe/NFC + GPS + Commute
	/worker-profile	Profile	Settings hub
Earnings	/earnings	Earnings	Detailed breakdown
	/early-pay	EarlyPay	NEW: Instant pay (5% fee)
Shifts	/shift-details/:id	ShiftDetails	Shift info
	/jobs	Jobs	Job search
	/availability	Availability	Schedule preferences
	/benefits	Benefits	Perks info
Profile/Onboarding	/personal-info	PersonalInfo	Basic details
	/emergency-contact	EmergencyContact	Safety info
	/experience	Experience	Work history
	/attire	Attire	Uniform confirmation
Profile/Compliance	/documents	Documents	ID uploads
	/certificates	Certificates	Certifications
	/tax-forms	TaxForms	Tax documents hub
	/taxforms/i9	FormI9	NEW: I-9 verification
	/taxforms/w4	FormW4	NEW: W-4 tax form
Profile/Finances	/bank-account	BankAccount	Payout setup
	/time-card	TimeCard	Hours log
Profile/Level Up	/krow-university	KrowUniversity	NEW: Training platform
	/trainings	Trainings	NEW: Skill courses
	/leaderboard	Leaderboard	NEW: Gamification
Profile/Support	/faqs	FAQs	Help articles
	/messages	Messages	Support chat
	/privacy	Privacy	Settings

Key NEW Features:

1. Advanced Clock-In System:

   • Swipe-to-check-in UI
   • NFC badge support
   • Commute Tracker (GPS-based ETA)
   • Lunch break modal
   • Geofencing validation

2. Early Pay (Earned Wage Access):

   • Request portion of earned wages early
   • 5% service fee
   • Enrollment flow with terms

3. Gamification & Training:

   • KROW University - Training courses
   • Leaderboard - Worker rankings
   • Trainings - Skill development

4. Tax Compliance:

   • Form I-9 - Employment eligibility
   • Form W-4 - Tax withholding

5. Enhanced Profile:

   • Time Card history
   • Documents vault
   • Certificate management

---

4.8 Complete Feature Comparison (All 3 Apps)

Feature	Legacy Mobile	Web Prototype	Mobile Prototype
Auth - Phone	✅	❌	✅
Auth - Email	❌	✅	✅
Order Types	1 (basic)	4 (one-time, rapid, recurring, permanent)	4 types
RAPID Orders (Voice)	❌	❌	✅ NEW
Clock In - QR	✅	❌	❌
Clock In - Swipe	❌	❌	✅ NEW
Clock In - NFC	❌	❌	✅ NEW
Commute Tracker	❌	❌	✅ NEW
Early Pay	❌	❌	✅ NEW
KROW University	❌	❌	✅ NEW
Leaderboard	❌	❌	✅ NEW
Tax Forms (I-9, W-4)	❌	❌	✅ NEW
Forecast Reports	❌	❌	✅ NEW
Verify Attire	❌	❌	✅ NEW
Smart Assignment	❌	✅	❌
Conflict Detection	❌	✅	❌
Savings Engine	❌	✅	❌
Vendor Marketplace	❌	✅	❌
Staff Profile (complete)	✅	Basic	Enhanced
Penalty System	✅	❌	❌
Staff Rating	✅	❌	❌

4.9 Source Code Locations

Component	Location	Tech
Web Prototype Source	internal/launchpad/prototypes-src/web/	React + TypeScript
Mobile Client Prototype	internal/launchpad/prototypes-src/mobile/client/	Flutter + Dart
Mobile Staff Prototype	internal/launchpad/prototypes-src/mobile/staff/	Flutter + Dart
Legacy Client Mobile	_legacy/apps/krow_client_context.md	Flutter (context doc)
Legacy Staff Mobile	_legacy/apps/krow_staff_context.md	Flutter (context doc)
Legacy Backend	_legacy/apps/php_backend_context.md	PHP/Laravel
New Backend	backend/dataconnect/	Firebase Data Connect

---

5. Data Connect & Development Strategy

5.1 Feature-Driven Schema Evolution

Principle: The Data Connect schema is not pre-designed. It evolves iteratively as features are implemented.

Feature Implementation Flow:
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Pick Feature   │ ──► │  Define Schema   │ ──► │  Implement UI    │
│   from Sprint    │     │  Tables/Queries  │     │  with SDK        │
└──────────────────┘     └──────────────────┘     └──────────────────┘
         │                        │                        │
         │                        │                        │
         ▼                        ▼                        ▼
    No mocks!              Just enough               Generated SDK
    Real data              for feature               guarantees types
    from start

5.2 No Mock Data Policy

Why no mocks?

1. Data Connect generates type-safe SDKs automatically
2. Mocks create drift between expected and actual schemas
3. Real data surfaces integration issues early
4. Reduces "works on my machine" problems

Instead of mocks:

• Use Firebase emulator suite for local development
• Seed development database with realistic test data
• Write schema migrations as features are added

5.3 Sprint 3 Schema Strategy

For each feature in Sprint 3:

1. Identify Data Requirements

   • What entities does this feature need?
   • What fields are required vs optional?
   • What relationships exist?

2. Write Schema Incrementally

   # backend/dataconnect/schema/event.gql
   type Event @table {
     id: UUID! @default(expr: "uuidV4()")
     name: String!
     status: EventStatus!
     date: Date!
     business: Business! @relation
     hub: Hub @relation
     shifts: [EventShift!]! @relation
     createdAt: Timestamp! @default(expr: "request.time")
   }
   

3. Define Queries/Mutations

   # backend/dataconnect/queries/events.gql
   query ListEvents($status: EventStatus) @auth(level: USER) {
     events(where: { status: { eq: $status } }) {
       id, name, status, date
       business { name }
     }
   }
   

4. Generate SDK & Implement UI

   firebase dataconnect:sdk:generate
   

5.4 Development Environment Setup

# Prerequisites
node -v    # >= 20.x
pnpm -v    # latest
fvm use    # Flutter version management
firebase --version  # >= 13.x

# Setup
git clone <repo>
cd krow-workforce-web
pnpm install
firebase login
firebase use development

# Start development
make dev              # Start all services
make dev-web          # Web only
make dev-mobile       # Mobile emulators
make sync-prototypes  # Sync visual references

5.5 Recommended Sprint 3 Feature Order

Based on minimal dependencies:

1. Authentication Flow (depends: Firebase Auth only)
2. Staff Profile Basics (depends: Auth)
3. Event List View (depends: Auth, basic schema)
4. Event Creation (depends: Auth, Events schema)
5. Shift Assignment (depends: Events, Staff)
6. Time Tracking (depends: Assignments)
7. Invoice Generation (depends: Completed shifts)

---

6. Definition of Done (DoD)

6.1 Feature-Level DoD (MVP Phase)

A feature is DONE when:

• Schema: Data Connect schema defined and deployed
• SDK: Generated SDK integrated into app
• UI: All screens implemented per prototype design
• Logic: Business logic working correctly
• Manual Testing: Feature tested directly in the application (happy path + edge cases)
• Security: Auth rules validated
• Accessibility: Basic a11y compliance
• Documentation: API documented in schema comments
• Review: Code reviewed and approved

Note (MVP): For rapid MVP delivery, we focus on manual/integration testing directly in applications rather than unit tests. Automated test coverage will be added post-MVP.

6.2 Sprint-Level DoD

A sprint is DONE when:

• All planned features meet Feature DoD
• No P0 bugs in staging environment
• Performance: <3s initial load, <500ms interactions
• Security audit passed (no critical vulnerabilities)
• Staging deployed and validated
• Demo-ready for stakeholders
• Documentation updated

6.3 Code Quality Standards

Aspect	Standard
Linting	Zero ESLint/Dart analyzer errors
Formatting	Prettier (JS/TS), dart format
Types	Strict TypeScript, no any
Commits	Conventional commits format
PRs	Template completed, 1+ approval
Testing (MVP)	Manual testing in application

6.4 Commit Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat(events): add event creation form
fix(auth): handle token expiration correctly
docs(readme): update setup instructions

6.5 Branch Strategy

main (production)
  └── dev (staging)
       └── feature/KROW-123-event-creation
       └── feature/KROW-124-shift-management
       └── fix/KROW-125-clock-in-bug

6.6 PR Checklist

## PR Checklist
- [ ] Code follows project conventions
- [ ] Self-reviewed changes
- [ ] Feature manually tested in application
- [ ] Documentation updated if needed
- [ ] No console.log/print statements
- [ ] Sensitive data not hardcoded
- [ ] Tested on emulator/device

---

Appendix A: Entity Relationship Summary

User (1) ─── (M) Membership ──┬── Business
                              ├── Hub
                              └── HubDepartment

Staff (1) ──┬── (M) StaffSkill ─── Skill ─── SkillCategory
            │         └── (M) StaffSkillKit ─── SkillKit
            ├── (M) StaffCertificate ─── Certificate
            ├── (1) StaffBankAccount
            ├── (1) StaffAccessibility
            ├── (M) StaffSchedule
            ├── (M) StaffEmergencyContact
            └── (M) EventShiftPositionStaff

Business (1) ──┬── (1) BusinessSetting
               ├── (1) BusinessContact
               ├── (M) BusinessContract
               ├── (M) Hub ──── (M) HubDepartment
               └── (M) Event ──── (M) EventShift ──── (M) EventShiftPosition
                          │
                          └── (M) Invoice ──── (M) InvoiceItem

---

Appendix B: Status Enums Reference

Event Status

draft → pending → assigned → confirmed → active → finished → completed → closed

Assignment Status

assigned | confirmed | ongoing | completed | canceled_by_staff | decline_by_staff | canceled_by_business | canceled_by_admin | requested_replace | no_showed

Staff Status

registered | pending | verified | blocked | inactive | completed_profile

Invoice Status

open | disputed | resolved | verified | overdue | reconciled | paid

Payment Status

new | confirmed_by_admin | confirmed_by_staff | decline_by_staff | sent | paid | failed | canceled

---

Appendix C: Key Files Reference

Purpose	Location
Vision document	docs/00-vision.md
Backend API spec (legacy)	docs/01-backend-api-specification.md
CI/CD config	docs/02-codemagic-env-vars.md
Contributing guide	docs/03-contributing.md
Prototype sync	docs/04-sync-prototypes.md
Legacy PHP context	_legacy/apps/php_backend_context.md
Legacy Client context	_legacy/apps/krow_client_context.md
Legacy Staff context	_legacy/apps/krow_staff_context.md
Architecture diagrams	internal/launchpad/assets/diagrams/
Data Connect schemas	backend/dataconnect/

---

This document is the source of truth for team onboarding. Update it as the project evolves.