# 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
(Business)"]:::clientApp
StaffApp["Staff App
(Workers)"]:::staffApp
end
subgraph Core_Platform["KROW Web Platform"]
direction TB
AdminPanel["Admin Dashboard
(Laravel Nova)"]:::backend
APIServer["GraphQL API
(Laravel Lighthouse)"]:::backend
Database[("Central Database
(PostgreSQL)")]:::db
end
subgraph External_Services["Cloud Services"]
direction TB
Firebase["Firebase
(Auth/Push)"]:::external
Maps["Google Maps
(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.