# KROW Legacy Ecosystem: System Bible

**Status:** Official System Constitution
**Version:** 1.0.0
**Date:** 2026-02-06
**Scope:** KROW Legacy Ecosystem (Client App, Staff App, Web Platform)

---

## 1. Executive Summary

The **KROW Legacy Ecosystem** is a comprehensive digital marketplace designed to revolutionize the temporary staffing industry. It eliminates the friction of traditional agencies by directly connecting **businesses** (restaurants, event organizers) with **temporary workers** (wait staff, security, chefs) through a unified, automated platform.

**Why It Exists:**
The traditional staffing model is slow, opaque, and manual (spreadsheets, phone calls). This ecosystem digitizes the entire lifecycle—from finding staff and verifying their skills to tracking attendance and processing payments—creating a transparent, efficient market for flexible work.

**Who It Serves:**
1.  **Business Owners ("Clients"):** Who need on-demand, vetted staff without the administrative burden.
2.  **Workers ("Staff"):** Who seek flexible shifts, instant access to job opportunities, and reliable payment.
3.  **Operations Teams:** Who manage the marketplace, ensuring quality, compliance, and dispute resolution.

**Value Proposition:**
"A trusted, transparent, and real-time workforce marketplace where businesses get reliability and workers get flexibility, powered by a single source of truth."

---

## 2. System Vision & Product Principles

### Core Goals
1.  **Frictionless Connection:** Reduce the time to fill a shift from days to minutes.
2.  **Trust through Transparency:** Both sides (Client and Staff) must have total visibility into profiles, ratings, and attendance.
3.  **Operational Excellence:** Automate low-value tasks (invoicing, timesheets) so humans can focus on high-value tasks (quality assurance, service).

### Product Principles
*   **Mobile-First for Users:** The primary interaction point for Clients and Staff is their phone. The experience must be fast, intuitive, and resilient to poor network conditions.
*   **Centralized Truth:** Business logic lives on the Server, not the Client. Mobile apps are "smart viewers" but never the final authority.
*   **Compliance is Mandatory:** The system must strictly enforce legal and operational requirements (e.g., "No uniform, no work").
*   **Offline Resilience:** Staff must be able to perform critical actions (Clock In/Out) even in basements or fields with no signal.

### What We Solve vs. What We Don't
*   **WE SOLVE:** Shift discovery, booking, attendance verification, invoicing, and payout calculation.
*   **WE DO NOT SOLVE:** Direct employment contracts (staff are independent contractors or agency employees), specialized tax advice, or instant banking transfers (we facilitate, we don't hold funds).

---

## 3. Ecosystem Overview

The ecosystem is composed of three distinct applications that function as a single organic unit.

| Application | Name | Primary User | Platform | Core Responsibility |
| :--- | :--- | :--- | :--- | :--- |
| **1. Client App** | `pineDev_krow-mobile-client-app` | Business Owners | Mobile (Flutter) | **Demand Generation.** Posting shifts, managing venues, verifying staff presence. |
| **2. Staff App** | `pineDev_krow-mobile-staff-app` | Temporary Workers | Mobile (Flutter) | **Supply Fulfilment.** Finding work, proving compliance, executing shifts. |
| **3. Web Platform** | `pineDev_legendary-web-app` | Admin / System | Web (Laravel) | **The Brain.** Marketplace orchestration, data storage, financial processing, admin control. |

**Conceptual Fit:**
Imagine a ride-sharing service. The **Client App** is the passenger requesting a ride. The **Staff App** is the driver accepting the ride. The **Web Platform** is the dispatch center managing the map, prices, and safety.

---

## 4. System Architecture Overview

The system follows a **Hub-and-Spoke** architecture. The Web Platform is the central Hub; the mobile applications are the Spokes.

### Architecture Style
*   **Monolithic Backend / Smart Mobile Clients:** We utilize a robust, monolithic backend (Laravel) to ensure data integrity and simplified deployment, coupled with rich mobile clients (Flutter) that handle UI/UX complexity.
*   **GraphQL Communication:** All apps communicate via a strictly typed GraphQL API. This decoupling allows mobile apps to evolve their UI without constantly requiring backend changes.

### System Boundaries
*   **Network Boundary:** The Mobile Apps communicate over the public internet to the Web Platform's API Gateway.
*   **Security Boundary:** Authentication (Firebase) happens at the edge. No request passes to the core logic without a valid identity token.
*   **Data Boundary:** Mobile apps cache data but own nothing. The Database behind the Web Platform is the only permanent record.

### Architecture Diagram

```mermaid
flowchart TD
    %% Define Styles
    classDef clientApp fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef staffApp fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
    classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef db fill:#eee,stroke:#333,stroke-width:2px,color:#333
    classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c

    subgraph Mobile_Apps["Mobile Ecosystem"]
        direction TB
        ClientApp["Client App<br/>(Business)"]:::clientApp
        StaffApp["Staff App<br/>(Workers)"]:::staffApp
    end

    subgraph Core_Platform["KROW Web Platform"]
        direction TB
        AdminPanel["Admin Dashboard<br/>(Laravel Nova)"]:::backend
        APIServer["GraphQL API<br/>(Laravel Lighthouse)"]:::backend
        Database[("Central Database<br/>(PostgreSQL)")]:::db
    end

    subgraph External_Services["Cloud Services"]
        direction TB
        Firebase["Firebase<br/>(Auth/Push)"]:::external
        Maps["Google Maps<br/>(Location)"]:::external
    end

    %% Communication Flows
    ClientApp <-->|GraphQL| APIServer
    StaffApp <-->|GraphQL| APIServer
    AdminPanel <-->|Internal| APIServer
    APIServer <-->|SQL| Database
    Mobile_Apps -.->|Auth| Firebase
    Mobile_Apps -.->|Location| Maps
```

---

## 5. Application Responsibility Matrix

This matrix prevents "logic creep" where business rules accidentally migrate into the mobile apps.

| Feature Domain | Client App | Staff App | Web Platform (Backend) |
| :--- | :--- | :--- | :--- |
| **User Accounts** | Sign In / Profile Edit | Sign In / Profile Edit | **MASTER RECORD.** Validation, Ban/Approve. |
| **Events/Shifts** | **CREATE / EDIT.** Define needs. | **READ / ACCEPT.** Browse & Book. | **VALIDATE.** Ensure availability, match skills. |
| **Staff Selection** | View assigned staff. | N/A | Match algorithms, Notification triggers. |
| **Attendance** | View status, Manual Override. | **EXECUTE.** QR Scan / Check-in. | **VERIFY.** Validate Time & Geolocation. |
| **Payments** | View Invoices, Pay. | View Earnings. | **CALCULATE.** Rates * Hours + Tax + Fees. |
| **Notifications** | Receive alerts. | Receive alerts. | **DISPATCH.** Decide who gets alerted and when. |
| **Compliance** | N/A | Upload Docs, Complete Checklists. | **AUDIT.** Verify docs, enforce expiry rules. |

**Crucial Rule:** Mobile Apps **DISPLAY** and **REQUEST**. The Web Platform **DECIDES** and **COMMITS**.

---

## 6. Use Cases (Core Canon)

These are the officially recognized system workflows.

### Group A: Onboarding & Identity
*   **UC-01: Staff Registration & Verification** (Staff App -> Web Platform)
    *   Staff signs up, uploads docs. Web Platform holds status as "Pending" until Admin approves.
*   **UC-02: Client Business Setup** (Client App -> Web Platform)
    *   Client creates account, defines venues (Hubs). Web Platform validates addresses via Maps.

### Group B: The Marketplace Loop
*   **UC-03: Shift Creation** (Client App -> Web Platform)
    *   Client defines role, time, rate. Web Platform publishes to eligible staff.
*   **UC-04: Shift Discovery & Booking** (Staff App -> Web Platform)
    *   Staff sees job, accepts it. Web Platform locks the slot and confirms booking.

### Group C: Operational Execution
*   **UC-05: Pre-Shift Compliance** (Staff App -> Web Platform)
    *   Staff confirms uniform/tools. App blocks clock-in until done.
*   **UC-06: Attendance (Clock In/Out)** (Staff App -> Client App -> Web Platform)
    *   Staff scans Client QR. Platform records timestamp & location. Updates Client view instantly.
*   **UC-07: Live Monitoring** (Client App -> Web Platform)
    *   Client sees who is on-site, late, or missing.

### Group D: Finance & Closeout
*   **UC-08: Ratings & Feedback** (Client App -> Web Platform)
    *   Client rates staff performance. Platform updates Staff reputation score.
*   **UC-09: Payroll Calculation** (Web Platform Internal)
    *   System calculates final pay based on verified hours.
*   **UC-10: Invoicing** (Web Platform -> Client App)
    *   System generates PDF invoice. Client views/downloads in app.

---

## 7. Cross-Application Interaction Rules

1.  **No Direct P2P:** The Client App and Staff App **NEVER** talk directly to each other. They communicate exclusively through the Web Platform.
    *   *Why?* Security and audit trails.
2.  **QR/NFC Exception:** The only "direct" interaction is the physical scanning of a QR code or NFC tag. This creates a data packet sent to the server, not a direct network connection between phones.
3.  **Push, Don't Poll:** Apps should not constantly ask "Is there an update?". The Platform sends Push Notifications to trigger a data refresh.
4.  **Graceful Degradation:** If the Web Platform is unreachable, mobile apps must allow read-only access to cached data (e.g., "My Schedule") but disable write actions (e.g., "Accept Shift").

---

## 8. Data Ownership & Source of Truth

| Data Domain | Source of Truth | Read Access | Write Access |
| :--- | :--- | :--- | :--- |
| **Staff Profile** | Web Database | Staff App (Own), Client App (Assigned), Admin | Staff (Draft), Admin (Approve) |
| **Events/Shifts** | Web Database | Client App (Own), Staff App (Public) | Client (Create), Admin (Override) |
| **Timesheets** | Web Database | Client & Staff (View) | System (Automated), Admin (Correction) |
| **Financials** | Web Database | Client (Invoices), Staff (Earnings) | System (Calculated Only) |
| **Chat/Msgs** | Web Database | Relevant Users | Sender |

**Principle:** "If it isn't in the Web Database, it didn't happen." Local storage on phones is temporary cache only.

---

## 9. Security & Access Model

### Authentication
*   **Provider:** Firebase Authentication.
*   **Philosophy:** "Trust but Verify." We trust Firebase to say *who* someone is (Identity). We trust our own database to say *what* they can do (Permissions).

### Authorization (RBAC)
*   **Role: Client:** Can only see *their* Hubs, *their* Events, and Staff *assigned* to them.
*   **Role: Staff:** Can only see *public* shifts they qualify for, and *their own* financial data.
*   **Role: Admin:** Has god-mode access via the Web Panel, audited by logs.

### Trust Boundaries
*   **Mobile Apps are Untrusted:** We assume the mobile app could be hacked or modified. Therefore, the API validates EVERY request. (e.g., A hacked Staff App sending "I worked 24 hours" will be rejected by server logic).

---

## 10. Non-Negotiables & Guardrails

1.  **No Business Logic in UI:** Flutter widgets must never calculate pay, taxes, or availability. They only display values provided by the API.
2.  **Strict Typing:** GraphQL schemas must be strictly typed. No `JSON` blobs unless absolutely necessary.
3.  **English Only:** Code, comments, and database columns must be in English. Localization happens at the UI layer only.
4.  **Immutable Financials:** Once a shift is "Paid," its record can never be modified, only reversed via a new "Correction" transaction.
5.  **Location Required:** Clock-in actions MUST include GPS coordinates. If GPS is missing, the action is flagged for review.

---

## 11. Known Constraints & Assumptions

*   **Assumption:** Clients and Staff have smartphones with working cameras (for QR) and GPS.
*   **Assumption:** Internet connectivity is available for Shift Creation and Booking. (Only Clock-in supports temporary offline mode).
*   **Constraint:** The system currently handles a single currency per deployment.
*   **Constraint:** Notifications are "best effort" via Firebase; they are not guaranteed to arrive instantly.

---

## 12. Glossary

*   **Hub:** A physical location or venue owned by a Client (e.g., "Downtown Stadium").
*   **Shift:** A specific time block requiring a worker (e.g., "Friday 18:00-22:00").
*   **Position:** A specific role required for a shift (e.g., "Head Waiter").
*   **Clock-In:** The digital act of starting work, verified by location and time.
*   **Admin Panel:** The web interface for KROW operations staff.
*   **Marketplace:** The collection of all open, unassigned shifts visible to staff.
*   **BLoC:** (Business Logic Component) The code pattern used in the mobile apps to manage state.
*   **GraphQL:** The data query language used for API communication.
