Files

Achintha Isuru b8d07380c0 replace the "Krow" with "KROW"

2026-02-26 15:13:26 -05:00

13 KiB

Raw Permalink Blame History

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:

Business Owners ("Clients"): Who need on-demand, vetted staff without the administrative burden.
Workers ("Staff"): Who seek flexible shifts, instant access to job opportunities, and reliable payment.
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

Frictionless Connection: Reduce the time to fill a shift from days to minutes.
Trust through Transparency: Both sides (Client and Staff) must have total visibility into profiles, ratings, and attendance.
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

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

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.
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.
Push, Don't Poll: Apps should not constantly ask "Is there an update?". The Platform sends Push Notifications to trigger a data refresh.
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

No Business Logic in UI: Flutter widgets must never calculate pay, taxes, or availability. They only display values provided by the API.
Strict Typing: GraphQL schemas must be strictly typed. No JSON blobs unless absolutely necessary.
English Only: Code, comments, and database columns must be in English. Localization happens at the UI layer only.
Immutable Financials: Once a shift is "Paid," its record can never be modified, only reversed via a new "Correction" transaction.
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.

13 KiB Raw Permalink Blame History