# The Krow Platform System Bible

**Status:** Official / Living Document
**Version:** 1.0.0

---

## 1. Executive Summary

### What the System Is
The **Krow Platform** is a multi-sided workforce management ecosystem that digitizes the entire lifecycle of temporary staffing. It replaces fragmented, manual processes (phone calls, spreadsheets, paper timesheets) with a unified digital infrastructure connecting businesses ("Clients") directly with temporary workers ("Staff").

### Why It Exists
The temporary staffing industry suffers from friction, lack of transparency, and delayed payments. Businesses struggle to find reliable staff quickly, while workers face uncertain schedules and slow wage access. Krow exists to remove this friction, ensuring shifts are filled instantly, work is verified accurately, and payments are processed swiftly.

### Who It Serves
1.  **Clients (Businesses):** Venue managers and owners who need on-demand or scheduled staff.
2.  **Staff (Workers):** Individuals seeking flexible, temporary employment opportunities.
3.  **Admins (Operations):** Internal teams managing the marketplace, compliance, and financial flows.

### High-Level Value Proposition
Krow transforms labor from a manual logistical headache into a streamlined digital asset. For clients, it provides "staff on tap" with verified compliance. For workers, it offers "freedom and instant pay." For the platform operators, it delivers data-driven oversight of a complex marketplace.

---

## 2. System Vision & Product Principles

### Core Goals
1.  **Immediacy:** Reduce the time-to-fill for urgent shifts from hours to minutes.
2.  **Accuracy:** Eliminate payroll disputes through GPS-verified digital timesheets.
3.  **Compliance:** Automate the enforcement of legal and safety requirements (attire, certifications).

### Problems It Intentionally Solves
*   **The "No-Show" Epidemic:** By creating a transparent marketplace with reliability ratings.
*   **Payroll Latency:** By enabling "Early Pay" features rooted in verified digital time cards.
*   **Administrative Bloat:** By automating invoice generation and worker onboarding.

### Problems It Intentionally Does NOT Solve
*   **Full-Time Recruitment:** This system is optimized for shift-based, temporary labor, not permanent headhunting.
*   **Gig Economy "Tasking":** It focuses on professional hospitality and event roles, not general unskilled errands.

### Guiding Product Principles
*   **Mobile-First for Operations:** If a task happens on a job site (clocking in, checking coverage), it *must* be possible on a phone.
*   **Data as the Truth:** We do not rely on verbal confirmations. If it isn't in the system (GPS stamp, digital signature), it didn't happen.
*   **Separation of Concerns:** Clients manage demand; Staff manage supply; Admin manages the rules. These roles never blur.

---

## 3. Ecosystem Overview

The ecosystem comprises three distinct applications, each serving a specific user persona but operating on a shared reality.

### 1. Client Mobile Application (The "Requester")
*   **Platform:** Flutter (Mobile)
*   **Responsibility:** Demand generation. Allows businesses to post orders, track arriving staff in real-time, and approve work hours.
*   **Concept:** The "Remote Control" for the venue's staffing operations.

### 2. Staff Mobile Application (The "Worker")
*   **Platform:** Flutter (Mobile)
*   **Responsibility:** Supply fulfillment. Empowering workers to find jobs, manage their schedule, verify their presence (Clock In), and access earnings.
*   **Concept:** The worker's "Digital Agency" in their pocket.

### 3. Krow Web Application (The "HQ")
*   **Platform:** React (Web)
*   **Responsibility:** Ecosystem governance. The command center for high-level analytics, complex financial operations (invoicing/payouts), vendor management, and system administration.
*   **Concept:** The "Mission Control" for the business backend.

---

## 4. System Architecture Overview

The Krow Platform follows a **Service-Oriented Architecture (SOA)** where multiple front-end clients interface with a shared, monolithic logical backend (exposed via API Gateway).

### Architectural Style
*   **Centralized State:** A single backend database serves as the source of truth for all apps.
*   **Role-Based Access:** The API exposes different endpoints and data views depending on the authenticated user's role (Client vs. Staff).
*   **Event-Driven Flows:** Key actions (e.g., "Shift Posted") trigger downstream effects (e.g., "Push Notification Sent") across the ecosystem.

### System Boundaries
The "System" encompasses the three front-end apps and the shared backend services. External boundaries are drawn at:
*   **Payment Gateways:** We initiate transfers, but the actual money movement is external.
*   **Maps/Geolocation:** We consume location data but do not maintain mapping infrastructure.
*   **SMS/Identity:** We offload OTP delivery to specialized providers.

### Trust Boundaries
*   **Mobile Apps are Untrusted:** We assume any data coming from a client device (GPS coordinates, timestamps) could be manipulated and must be validated server-side.
*   **Web App is Semi-Trusted:** Admin actions are logged for audit but are assumed to be authorized operations.

```mermaid
flowchart TD
    subgraph Clients [Client Layer]
        CMA[Client Mobile App]
        SMA[Staff Mobile App]
        WEB[Web Admin Portal]
    end

    subgraph API [Interface Layer]
        Gateway[API Gateway]
    end

    subgraph Services [Core Service Layer]
        Auth[Identity Service]
        Ops[Operations Service]
        Finance[Financial Service]
    end

    subgraph Data [Data Layer]
        DB[(Central Database)]
    end

    CMA --> Gateway
    SMA --> Gateway
    WEB --> Gateway
    Gateway --> Services
    Services --> DB
```

---

## 5. Application Responsibility Matrix

| Feature Domain | Client App (Mobile) | Staff App (Mobile) | Web App (Admin/Ops) |
| :--- | :--- | :--- | :--- |
| **User Onboarding** | Register Business | Register Worker | Onboard Vendors |
| **Shift Management** | **Create** & Monitor | **Claim** & Execute | **Oversee** & Resolve |
| **Time Tracking** | Approve / Dispute | Clock In / Out | Audit Logs |
| **Finance** | Pay Invoices | Request Payout | Generate Bills |
| **Compliance** | Verify Attire | Upload Docs | Verify Docs |
| **Analytics** | View My Venue Stats | View My Earnings | Global Market Analysis |

### Critical Rules
*   **Client App MUST NOT** access worker financial data (bank details, total platform earnings).
*   **Staff App MUST NOT** see client billing rates or internal venue notes.
*   **Web App MUST** be the only place where global system configurations (e.g., platform fees) are changed.

---

## 6. Use Cases

The following are the **official system use cases**. Any feature request not mapping to one of these must be scrutinized.

### A. Staffing Operations
1.  **Post Urgent Shift (Client):**
    *   *Pre:* Valid client account.
    *   *Flow:* Select Role -> Set Qty -> Post.
    *   *Post:* Notification sent to eligible workers.
2.  **Claim Shift (Staff):**
    *   *Pre:* Worker meets compliance reqs.
    *   *Flow:* View Job -> Accept.
    *   *Post:* Shift is locked; Client notified.
3.  **Execute Shift (Staff):**
    *   *Pre:* On-site GPS verification.
    *   *Flow:* Clock In -> Work -> Clock Out.
    *   *Validation:* Location check passes.
4.  **Approve Timesheet (Client):**
    *   *Pre:* Shift completed.
    *   *Flow:* Review Hours -> Approve.
    *   *Post:* Payment scheduled.

### B. Financial Operations
5.  **Process Billing (Web/Admin):**
    *   *Flow:* Aggregate approved hours -> Generate Invoice -> Charge Client.
6.  **Request Early Pay (Staff):**
    *   *Pre:* Accrued unpaid earnings.
    *   *Flow:* Select Amount -> Confirm -> Transfer.

### C. Governance
7.  **Verify Compliance (Web/Admin):**
    *   *Flow:* Review uploaded ID -> Mark as Verified.
    *   *Post:* Worker eligible for shifts.
8.  **Strategic Analysis (Web/Client):**
    *   *Flow:* View Savings Engine -> Adopt Recommendation.

---

## 7. Cross-Application Interaction Rules

### Communication Patterns
*   **Indirect Communication:** Apps NEVER speak peer-to-peer.
    *   *Correct:* Client App posts order -> Backend -> Staff App receives notification.
    *   *Forbidden:* Client App sends data directly to Staff App via Bluetooth/LAN.
*   **Push Notifications:** Used as the primary signal to "wake up" an app and fetch fresh data from the server.

### Dependency Direction
*   **Downstream Dependency:** The Mobile Apps depend on the Web App's configuration (e.g., if Admin adds a new "Role Type" on Web, it appears on Mobile).
*   **Upstream Data Flow:** Operational data flows *up* from Mobile (Clock-ins) to Web (Reporting).

### Anti-Patterns to Avoid
*   **"Split Brain" Logic:** Business logic (e.g., "How is overtime calculated?") must live in the Backend, NOT duplicated in the mobile apps.
*   **Local-Only State:** Critical data (shift status) must never exist only on a user's device. It must be synced immediately.

---

## 8. Data Ownership & Source of Truth

| Data Domain | Source of Truth | Write Access | Read Access |
| :--- | :--- | :--- | :--- |
| **User Identity** | Auth Service | User (Self), Admin | System-wide |
| **Shift Status** | Order Service | Client (Create), Staff (Update status) | All (Context dependent) |
| **Time Cards** | Database | Staff (Create), Client (Approve) | Admin, Payroll |
| **Compliance Docs** | Worker Profile | Staff (Upload), Admin (Verify) | Client (Status only) |
| **Platform Rates** | System Config | Admin | Read-only |

### Consistency Principle
**"The Server is Right."** If a mobile device displays a shift as "Open" but the server says "Filled," the device is wrong and must refresh. We prioritize data integrity over offline availability for critical transaction states.

---

## 9. Security & Access Model

### User Roles
1.  **Super Admin:** Full system access.
2.  **Client Manager:** Access to own venue data only.
3.  **Worker:** Access to own schedule and public job board only.

### Authentication Philosophy
*   **Zero Trust:** Every API request must carry a valid, unexpired token.
*   **Session Management:** Mobile sessions are persistent (long-lived tokens) for usability; Web sessions (Admin) are shorter for security.

### Authorization Boundaries
*   **Horizontal Separation:** Client A cannot see Client B's orders. Worker A cannot see Worker B's pay.
*   **Vertical Separation:** Staff cannot access Admin APIs.

---

## 10. Non-Negotiables & Guardrails

1.  **No GPS, No Pay:** A clock-in event *must* have valid geolocation data attached. No exceptions.
2.  **Compliance First:** A worker cannot claim a shift if their required documents (e.g., Food Handler Card) are expired. The system must block this at the API level.
3.  **Immutable Audit Trail:** Once a timesheet is approved and paid, it cannot be deleted or modified, only reversed via a new corrective transaction.
4.  **One Account Per Person:** Strict identity checks to prevent duplicate worker profiles.

---

## 11. Known Constraints & Assumptions

*   **Connectivity:** The system assumes a reliable internet connection for critical actions (Claiming, Clocking In). Offline mode is limited to read-only views of cached schedules.
*   **Device Capability:** We assume worker devices have functional GPS and Camera hardware.
*   **Payment Timing:** "Instant" pay is subject to external banking network delays (ACH/RTP) and is not truly real-time in all cases.

---

## 12. Glossary

*   **Shift:** A single unit of work with a start time, end time, and role.
*   **Order:** A request from a client containing one or more shifts.
*   **Clock-In:** The digital timestamp marking the start of work, verified by GPS.
*   **Rapid Order:** A specific order type designed for immediate (<24h) fulfillment.
*   **Early Pay:** A financial feature allowing workers to withdraw accrued wages before the standard pay period ends.
*   **Hub:** A specific physical location or venue belonging to a Client.
*   **Compliance:** The state of having all necessary legal and safety documents verified.
